Agents overview

An agent definition is a reusable configuration that describes who an agent is, what it can do, and how it behaves. Agent definitions are stored in the agent_definitions table and can be reused across chats, graphs, panels, and orchestrators.

Agent definitions

Each agent has:

Field	Description
name	Display name
description	What the agent does (included in system prompt)
model_config	JSON with model name and provider settings
soul_md	Personality and behavior instructions (SOUL.md)
skills	Skills from your Library to enable
tools	Individual tools from your Library to grant
is_published	Whether visible to orchestrators and other agents

An agent definition brings together several concepts:

• Identity & description — the agent’s name and what it does, which seed the system prompt.
• SOUL personality — a SOUL.md file with personality and behavior instructions.
• Skills — bundled capabilities with prompt context and tools (e.g., web_search, code_analysis), selected from your Library skills.
• Tools — individual tool integrations (shell, file system, web) granted from your Library tools.
• Memory strategy — how the agent retains conversation context. See Agent memory.
• Comms policy — how the agent communicates with other agents. See Agent comms.

The native agent runtime

Chatty runs autonomous agents on a native Rust agent runtime. The runtime provides:

• Skills: bundled capabilities with prompt context and tools (e.g., web_search, code_analysis)
• Tools: external tool integrations (shell, file system, web)
• Agent templates (Hands): reusable starting points for new agents
• Memory: in-memory or persistent conversation memory
• Agent loop: multi-turn tool calling until the agent produces a final answer

System prompt construction

When a SubAgent node runs, the system prompt is built from the agent’s identity, its available tools (skills + tools + agent templates), and its SOUL personality file:

# Agent Identity
You are {name}. {description}

# Tool Call Behavior
You have access to tools. To use a tool, respond with a tool_use block...

# Available Tools
- shell_exec: Execute a shell command
- web_search: Search the web
- ...

# SOUL.md
{soul_md content}

# Skills Context
{skill prompt context}

Provider integration

The runtime adapts Chatty’s LlmProvider trait to the agent loop’s driver interface:

• Converts between the agent loop’s message format and Chatty’s ChatMessage format
• Handles tool calling for Ollama (via send_with_tools())
• Falls back to text-based tool call parsing for models that emit tool calls as JSON text (e.g., qwen2.5)
• Routes stream() calls to complete() for providers that don’t support streaming with tools

Using agents in graphs

SubAgent node

The most powerful way to use agents. Runs the full agent loop:

1. Resolves tools from skills + direct tools + agent templates
2. Builds the structured system prompt
3. Creates an ephemeral session and memory
4. Runs the agent loop — the agent can make multiple tool calls
5. Streams all events (text deltas, tool executions) to the graph UI
6. Returns the agent’s final response as the node output

AgentComm node

For controlled multi-turn conversations with an agent:

1. Sends the initial message (expanded from template)
2. Gets the agent’s response
3. Feeds the response back as the next message
4. Repeats for conversation_turns rounds
5. Returns the final response

Orchestrator node

Magentic-One pattern for complex task decomposition:

1. The orchestrator LLM creates a plan from the task description
2. Delegates subtasks to available agents
3. Evaluates each agent’s result
4. Re-delegates if needed (up to max_delegations)
5. Synthesizes a final response from all delegation results

For multi-agent debate and delegation patterns, see Panels & orchestrators.

Agent Editor

The frontend Agent Editor (/studio → Agents tab) provides:

• Create/edit agent definitions with name, description, model, SOUL.md
• Select skills from your Library with skill content preview
• Select individual tools with grouped dropdown
• Publish/unpublish agents
• Test agents directly from the editor

You can also try agents interactively in the Agent playground.