Agent
The core class for AI agents with tools, memory, knowledge, and handoffs.Param Cluster Map
| Cluster | Legacy Params | Consolidated To | Status |
|---|---|---|---|
| Output | verbose, markdown, stream, metrics, reasoning_steps | output= | ✅ |
| Execution | max_iter, max_rpm, max_execution_time, max_retry_limit | execution= | ✅ |
| Memory | memory, auto_memory, claude_memory, user_id, session_id, db | memory= | ✅ |
| Knowledge | knowledge, retrieval_config, embedder_config | knowledge= | ✅ |
| Planning | planning, plan_mode, planning_tools, planning_reasoning | planning= | ✅ |
| Reflection | self_reflect, max_reflect, min_reflect, reflect_llm | reflection= | ✅ |
| Guardrails | guardrail, max_guardrail_retries, policy | guardrails= | ✅ |
| Web | web_search, web_fetch | web= | ✅ |
| Templates | system_template, prompt_template, response_template | templates= | ✅ |
| Caching | cache, prompt_caching | caching= | ✅ |
| LLM | llm, llm_config, function_calling_llm | llm= | ✅ |
base_url and api_key remain separate (connection/auth constraint).
Precedence Ladder
Instance > Config > Array > Dict > String > Bool > Default
Quick Start
Parameters Table
Core Identity
| Parameter | Type | Default | Description |
|---|---|---|---|
name | str | None | Agent name for identification |
role | str | None | Role/job title defining expertise |
goal | str | None | Primary objective |
backstory | str | None | Background context |
instructions | str | None | 💡 Canonical - Direct instructions (overrides role/goal/backstory) |
LLM Configuration
| Parameter | Type | Default | Description |
|---|---|---|---|
llm | str | Any | None | ✅ Model name ("gpt-4o") or LLM object |
model | str | Any | None | ✅ Alias for llm= |
base_url | str | None | Custom endpoint URL (kept separate) |
api_key | str | None | API key (kept separate) |
function_calling_llm | Any | None | ⚠️ Deprecated - use llm= |
llm_config | Dict | None | ⚠️ Deprecated - use llm= |
Tools & Capabilities
| Parameter | Type | Default | Description |
|---|---|---|---|
tools | List[Any] | None | Tools, functions, or MCP instances |
handoffs | List[Agent | Handoff] | None | Agents for task delegation |
allow_delegation | bool | False | ⚠️ Deprecated — use handoffs= |
allow_code_execution | bool | False | ⚠️ Deprecated — use execution=ExecutionConfig(code_execution=True) |
code_execution_mode | "safe" | "unsafe" | "safe" | ⚠️ Deprecated — use execution=ExecutionConfig(code_mode=) |
Deprecated Standalone Params
These still work for backward compatibility but emitDeprecationWarning. Use the consolidated config objects instead.
| Parameter | Type | Default | Replacement |
|---|---|---|---|
auto_save | str | None | memory=MemoryConfig(auto_save="name") |
rate_limiter | Any | None | execution=ExecutionConfig(rate_limiter=obj) |
verification_hooks | List[VerificationHook] | None | autonomy=AutonomyConfig(verification_hooks=[...]) |
Consolidated Feature Params
Each follows:False=disabled, True=defaults, Config=custom
| Parameter | Type | Default | Description |
|---|---|---|---|
memory | bool | MemoryConfig | None | Memory system |
knowledge | bool | List[str] | KnowledgeConfig | None | Knowledge sources |
planning | bool | PlanningConfig | False | Planning mode |
reflection | bool | ReflectionConfig | None | Self-reflection |
guardrails | bool | Callable | GuardrailConfig | None | Output validation |
web | bool | WebConfig | None | Web search/fetch |
context | bool | ContextConfig | False | Context management |
autonomy | bool | Dict | AutonomyConfig | None | Autonomy settings |
output | str | OutputConfig | None | Output preset or config |
execution | str | ExecutionConfig | None | Execution preset or config |
caching | bool | CachingConfig | None | Caching settings |
hooks | List | HooksConfig | None | Event hooks |
skills | List[str] | SkillsConfig | None | Agent skills |
templates | TemplateConfig | None | Template configuration |
Precedence Ladder
Resolution Order: Instance > Config > Array > Dict > String > Bool > DefaultWhen you pass a consolidated param, the resolver checks in this order:
- Instance - Already a config object? Use as-is
- Config - Dataclass instance? Use as-is
- Array -
["preset", {"override": value}]? Apply overrides - Dict -
{"key": value}? Convert to config - String -
"preset_name"or URL? Look up preset or parse URL - Bool -
True? Use defaults.False? Disable - Default -
None? Use default value
Usage Forms Table
| Form | Example | When to Use |
|---|---|---|
| Bool | memory=True | Enable with defaults |
| String preset | output="verbose" | Use predefined config |
| URL | memory="redis://localhost" | Backend-specific config |
| Dict | memory={"backend": "redis"} | Custom config as dict |
| Array + overrides | output=["verbose", {"stream": False}] | Preset + customization |
| Config instance | memory=MemoryConfig(backend="redis") | Full control |
Examples for Each Form
Presets & Options
Output Presets
| Preset | Description | Example |
|---|---|---|
"silent" | Zero output (default) | — |
"status" | Tool calls + response, no timestamps | ▸ get_weather → Sunny ✓ |
"trace" | Full trace with timestamps | [14:30:29] ▸ get_weather → Sunny [0.2s] ✓ |
"debug" | trace + metrics (no boxes) | Timestamps + token counts, cost |
"verbose" | Rich panels with Markdown | Task + Response panels |
"stream" | Real-time token streaming | Tokens appear as generated |
"json" | JSONL events | {"event": "tool_call", ...} |
"text", "actions" → "status" | "plain", "minimal" → "silent" | "normal" → "verbose"
Execution Presets
| Preset | max_iter | max_retry_limit |
|---|---|---|
"fast" | 10 | 1 |
"balanced" | 20 | 2 |
"thorough" | 50 | 5 |
"unlimited" | 1000 | 10 |
Memory Presets
| Preset | Backend |
|---|---|
"file" | Local file storage |
"sqlite" | SQLite database |
"redis" | Redis server |
"postgres" | PostgreSQL |
"mongodb" | MongoDB |
Web Presets
| Preset | search | fetch | provider |
|---|---|---|---|
"duckduckgo" | ✅ | ✅ | DuckDuckGo |
"tavily" | ✅ | ✅ | Tavily |
"google" | ✅ | ✅ | |
"search_only" | ✅ | ❌ | Default |
"fetch_only" | ❌ | ✅ | Default |
Reflection Presets
| Preset | min_iterations | max_iterations |
|---|---|---|
"minimal" | 1 | 1 |
"standard" | 1 | 3 |
"thorough" | 2 | 5 |
Guardrail Presets
| Preset | max_retries | on_fail |
|---|---|---|
"strict" | 5 | raise |
"permissive" | 1 | skip |
"safety" | 3 | retry |
Methods
Execution Methods
| Method | Streams by Default | Display | Use Case |
|---|---|---|---|
start(prompt, **kwargs) | ✅ Yes (in TTY) | ✅ Auto | Interactive/terminal use |
run(prompt, **kwargs) | ❌ No | ❌ No | Production/scripted use |
iter_stream(prompt, **kwargs) | ✅ Always | ❌ No | App integration (yields chunks) |
chat(prompt, ...) | Configurable | Configurable | Low-level execution |
Async Execution Methods
| Method | Streams by Default | Use Case |
|---|---|---|
astart(prompt, **kwargs) | ✅ Yes (in TTY) | Async interactive |
arun(prompt, **kwargs) | ❌ No | Async production |
achat(prompt, ...) | Configurable | Async low-level |
Other Methods
| Method | Description |
|---|---|
query(question, **kwargs) | Query knowledge base (RAG) |
retrieve(query, **kwargs) | Retrieve context from knowledge |
clear_history() | Clear chat history |
execute_tool(name, args) | Execute a tool dynamically |
Class Methods
| Method | Description |
|---|---|
from_template(uri, config, offline, **kwargs) | Create agent from template |
Common Recipes
Simple Agent with Instructions
Agent with Tools
Agent with Handoffs
Agent with Knowledge Base
Agent with Streaming
Choose the right method based on your use case:Streaming Precedence:
start(stream=True/False) overrides OutputConfig.stream.output="stream"setsstream=Trueby defaultstart(stream=False)can disable streaming even withoutput="stream"start(stream=True)enables streaming for any preset
Agent with Custom LLM
Agent with Consolidated Config
Async Support
The Agent class provides full async support:Multi-Agent Safe
Agents are designed to be multi-agent safe. Each agent maintains its own:- Chat history
- Memory instance
- Knowledge base
- Session state
See Also
- Agents Module - Multi-agent orchestration
- Handoff Module - Agent-to-agent handoffs
- Tools Module - Tool system
- Memory Module - Memory management
- Knowledge Module - Knowledge bases

