Admin Dashboard: Agents

An agent is a named AI role with instructions, a model, lifecycle settings, tools, MCP servers, and capabilities. Schemas decide where the agent is used and which other agents it may delegate to.

When to create an agent

Create a specialist when it has a distinct responsibility, tool boundary, model requirement, or context policy. Keep a single agent when splitting the work would only add handoff overhead.

The Agents list shows workspace agents separately from protected system agents. Search by name and open a row to edit it. Because an agent is global, a change affects every schema that uses that agent; review those schemas before changing a shared prompt, model, or tool assignment.

Create an agent

Open Agents and choose New Agent.
Enter a display name, URL-safe name, and focused system prompt.
Open the new agent and assign a Chat model or rely on the deployment default when one is advertised.
Choose a lifecycle:
- persistent retains session context and compacts it at the configured boundary;
- spawn starts fresh for each delegated task and releases that instance afterward.
Set Max Turn Steps, Context Size, and Max Turn Duration. Optionally set Max Step Duration to 0 (disabled) or 10–3600 seconds so one model or tool step cannot run indefinitely.
Set model parameters only when you need to override their defaults: temperature, Top P, maximum output tokens, and stop sequences.
Choose sequential or parallel tool execution, then attach built-in tools, MCP servers, and capabilities such as Memory, Knowledge, or Knowledge Graphs. For a browser or REST approval step, assign show_structured_output and use its resumable interrupt flow; the confirm_before field cannot be approved through the REST API.

The expected result is an agent that can be selected as a schema entry point or relation target. System agents appear separately and may have protected defaults.

Use a narrow system prompt that states the role, allowed actions, required tool workflow, and what the agent should do when evidence or authority is missing. Put business data in Knowledge, Knowledge Graphs, or MCP tools instead of copying changing records into the prompt.

Configure delegation

Delegation is not edited as an agent field. Open Schemas, select the workflow, and add a directed relation from the delegating agent to the target. The API’s can_spawn value is derived read-only output.

Nested delegation is supported when each edge exists. Avoid broad all-to-all graphs: each relation expands what an agent can ask another agent to do.

Test and troubleshoot

Test from the schema that uses the agent so the real relation graph and entry point are active. If the agent cannot answer, verify its model or the deployment default. If it cannot delegate, verify the schema relation. If a tool is missing, verify its agent assignment, capability settings, and MCP connection status. A step-duration timeout means the current model or tool call exceeded the agent’s limit; increase it only after checking the slow dependency.

Deleting an agent can be rejected while schemas, relations, or other resources still reference it; remove those dependencies deliberately first.

Manage agents as configuration

For reviewed environment promotion, declare the agent in a configuration bundle or a brewctl Agent resource. Keep credentials out of YAML and declare delegation on the Schema resource:

apiVersion: syntheticbrew/v1
kind: Agent
name: billing-specialist
model: primary-chat
lifecycle: spawn
system_prompt: |
  Resolve billing questions using only the assigned billing tools.
  Ask for clarification when the account or requested action is ambiguous.
capabilities:
  - type: memory
    enabled: true

Run brewctl validate and brewctl diff before applying a reviewed change. Configuration import does not include provider secrets, uploaded Knowledge documents, or every capability setting; verify the destination agent after promotion.