Agents & Lifecycle

An agent in ByteBrew is an LLM-powered entity with a defined identity (system prompt), capabilities (tools), and memory scope (lifecycle). Agents are the fundamental building blocks of your AI-powered workflows.

What is an agent?

At its core, an agent is a loop: receive input, reason about it using an LLM, optionally call tools to gather information or take actions, and return a response. The system prompt defines who the agent is and how it behaves.

• Identity — the system prompt gives the agent a role, personality, and knowledge boundaries.
• Capabilities — tools, MCP servers, and knowledge bases determine what the agent can do.
• Memory — the lifecycle setting controls whether the agent remembers previous conversations.
• Autonomy — the agent decides which tools to call and in what order based on the user’s request.

Lifecycle: persistent vs spawn

The lifecycle setting is one of the most important decisions you make when configuring an agent. It controls the agent’s memory scope:

Lifecycle	Description
persistent	Maintains context within a single session (conversation). Each new session starts fresh — there is no cross-session memory. Best for: customer-facing agents, personal assistants, support bots.
spawn	Single-use agent. Created for a specific task, runs with fresh context, terminates after completing the task, and returns the result to the parent agent. No memory between invocations. Best for: sub-agents, one-off research tasks, data processing.

agents:
  # Persistent: remembers customer history
  support-bot:
    model: glm-5
    lifecycle: persistent
    system: |
      You are a customer support agent. Remember
      previous interactions with each customer.

  # Spawn: fresh context, used for delegation
  researcher:
    model: qwen-3-32b
    lifecycle: spawn
    system: |
      Research the given topic thoroughly.
      Return a structured summary with sources.
    tools:
      - knowledge_search

When to use spawn

Use spawn for sub-agents in a multi-agent setup. When a supervisor spawns a researcher, the researcher gets a clean context focused solely on the research task. This keeps the sub-agent focused and prevents context pollution from unrelated conversations.

System prompts

Configure the agent’s identity, instructions, and behavior using the system: field in YAML or via the Admin Dashboard. The system prompt is the most important configuration for an agent — it defines the agent’s personality, role, capabilities, constraints, and output format. You can set it inline, as a multi-line block, or load it from an external file:

agents:
  # Inline (good for short prompts)
  greeter:
    model: glm-5
    system: "You are a friendly greeter. Welcome users and ask how you can help."

  # Multi-line inline (good for medium prompts)
  analyst:
    model: glm-5
    system: |
      You are a data analyst. When given data, you:
      1. Identify key trends and patterns
      2. Calculate relevant statistics
      3. Provide actionable recommendations

  # Long prompt using YAML multi-line block
  enterprise-agent:
    model: glm-5
    system: |
      You are an enterprise support agent for Acme Corp.
      # (paste the full prompt here using YAML multi-line block syntax)

Agent capabilities

Each agent can be configured with a unique combination of capabilities:

• Built-in tools — show_structured_output, manage_tasks, memory_recall, memory_store, knowledge_search, spawn_* (see Tools docs). Web search is available via MCP servers (Tavily, Brave, Exa).
• Custom HTTP tools — declarative API calls defined in YAML with type: http (see Tools docs).
• MCP servers — connect external APIs via Model Context Protocol (stdio or SSE transport).
• Knowledge base (RAG) — auto-indexed document folder for grounded responses (.md and .txt files).
• Sub-agent spawning — ability to create and delegate to other agents via can_spawn.

Capabilities

Capabilities are modules that extend an agent with additional tools and behaviors. Unlike regular tools, capabilities are managed in the Admin Dashboard and inject their tools automatically — you don’t list them in tools:.

Capability	Injected tools	Description
Memory	memory_recall, memory_store	Persistent cross-session memory. The agent can store and recall facts across conversations.
Knowledge	knowledge_search	RAG-based document search. The agent queries indexed documents to answer factual questions.

Enabling capabilities

In the Admin Dashboard, open an agent’s detail page and go to the Capabilities tab. Add a capability and configure its settings:

• Memory: configure retention period and memory limit.
• Knowledge: link one or more knowledge bases (document collections indexed for vector search).

Session memory vs persistent memory

ByteBrew has two distinct memory layers:

Layer	Scope	Storage
Session context	Within a single conversation	Held in the LLM’s context window. Automatically managed.
Persistent memory	Across sessions	Stored in the database. Requires the Memory capability.

Session context is automatic — the agent always sees the current conversation. Persistent memory is opt-in: the agent uses memory_store to explicitly save a fact and memory_recall to retrieve it in future sessions.

agents:
  personal-assistant:
    model: glm-5
    lifecycle: persistent
    system: |
      You are a personal assistant. Use memory_recall at the start
      of each conversation to recall relevant facts about the user.
      Use memory_store to save new preferences or important information
      the user shares.

Memory scope

Persistent memory is scoped to a (schema, user) pair. Two users chatting with the same schema have separate memory spaces and cannot see each other’s stored memories.

Schemas

A Schema is a workflow container that defines how agents are organized and how users interact with them. Every chat session is associated with a schema, not directly with an agent. See Schemas for the full reference.

Schema structure

• Entry agent — the agent that receives the user’s first message. It can spawn other agents.
• Agent relations — connections between agents that define the delegation tree (who can spawn whom).
• Chat Enabled — a toggle that controls whether the schema accepts chat requests.

Why schemas exist

Schemas let you build multi-agent workflows and expose them as a single chat endpoint. Instead of exposing individual agents, you expose a schema that routes messages to the right agents automatically.

Schema: "Customer Support"
├── Entry agent: router (receives all user messages)
├── Agent relations:
│   ├── router → billing-agent (via spawn)
│   └── router → technical-agent (via spawn)
└── Chat Enabled: true

Enabling chat

Toggle Chat Enabled on a schema in Admin Dashboard → Schemas. Once enabled, the schema accepts requests at:

POST /api/v1/schemas/{schema_id}/chat

The schema_id is the UUID shown in the Admin Dashboard URL.

---

What’s next

• Schemas
• Multi-Agent Orchestration
• Tools
• Admin: Agents