Agents & Lifecycle

An agent in SyntheticBrew 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.
• Context and memory — lifecycle controls how a delegated run is created; the Memory capability controls opt-in cross-session memory.
• 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 controls how the agent participates in a conversation or delegated task:

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: continues within one chat session
  support-bot:
    model: glm-5
    lifecycle: persistent
    system: |
      You are a customer support agent. Use earlier messages
      in this conversation when answering follow-up questions.

  # 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.

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 Admin editor, system_prompt in an imported config snapshot (system is accepted as an alias), or system_prompt in a brewctl Agent resource. The system prompt defines the agent’s role, constraints, tool-use guidance, and output format.

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)

Write an effective prompt

A reliable prompt usually contains:

1. Role and audience: what the agent is responsible for and who it serves.
2. Evidence rules: which Knowledge, graph, or MCP source it must consult before making a factual claim.
3. Tool workflow: when to call each assigned tool and which actions require user input or external authorization.
4. Boundaries: what the agent must not infer, expose, or change.
5. Failure behavior: what to say or do when data, identity, authority, or a dependency is missing.
6. Output expectations: the useful level of detail, citations, structure, and handoff information.

Keep changing facts and credentials out of the prompt. Put policy documents in Knowledge, exact records in Knowledge Graphs, and live data or actions behind MCP tools. Prompts guide the model; they do not replace authorization, validation, idempotency, or business rules in the receiving system.

Test the prompt with expected requests, ambiguous requests, unsupported questions, malicious instructions inside retrieved content, tool failures, and attempts to access another user’s data. Re-test after changing the model or tool catalog because those changes can alter how the same prompt behaves.

Agent capabilities

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

• Core built-in tools — show_structured_output and manage_tasks (see Tools docs). Memory and Knowledge tools are injected by capability bindings, delegation tools are generated from schema relations, and web search is available through an assigned MCP server.
• Custom HTTP tools — tools added by an Enterprise administrator. They are not part of config import/export; use MCP for an integration that should work in both Cloud and Enterprise.
• MCP servers — connect external tools over HTTP, Streamable HTTP, SSE, or Enterprise-approved stdio.
• Knowledge base (RAG) — add the Knowledge capability and link a knowledge base of uploaded documents (.txt, .md, .csv, .pdf, .docx) for grounded responses (see Knowledge / RAG).
• Agent delegation — ability to call another agent, declared as agent relations in a schema. SyntheticBrew generates a spawn_<target> tool for each outgoing relation.

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.
Knowledge Graphs	Generated list_*, get_*, and optional list_*_ids tools	Typed records from one or more configured graph bundles.

Enabling capabilities

In the Admin Dashboard, open an agent’s detail page, find Capabilities, and choose Add Capability. Expand the new capability, enable it, configure it, and save the agent:

• Memory: choose a retention period or unlimited retention, then set a maximum entry count or allow unlimited entries. When the entry limit is reached, the oldest entries are removed first.
• Knowledge: set Top-K and the similarity threshold here, then use the separate Knowledge page to link one or more knowledge bases to the agent.
• Knowledge Graphs: select one or more existing bundle names. The list must be non-empty and every name must be valid.

Session memory vs persistent memory

SyntheticBrew 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 workspace, schema, and user identifier. Two users chatting with the same schema have separate memory spaces, and the same user does not share memory across unrelated schemas.

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 delegate only along outgoing relations defined in the schema.
• 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

Open the schema’s Settings tab and turn on Accept chat requests. Once enabled, the schema accepts requests at:

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

The {name} value is the schema’s immutable DNS-label name, such as support-handbook. Resource UUIDs remain internal storage identifiers and are not used in schema API paths.

---

What’s next

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