Configure Your Agent
Keep native harness configuration explicit while using Agno run and session APIs.
Use named constructor arguments for common settings and native option objects for provider-specific behavior. Keep the same agent instance for successive calls; create a new session ID for an independent conversation.
Claude configuration
from agno.agents.claude import ClaudeAgent
from claude_agent_sdk import ClaudeAgentOptions
agent = ClaudeAgent(
id="claude-assistant",
model="claude-sonnet-5-5",
system_prompt="Answer support questions using the configured business tools.",
tools=[],
options=ClaudeAgentOptions(setting_sources=[], permission_mode="dontAsk"),
)Explicit non-None named fields override native options, including False and empty collections. Prefer options over the deprecated options_kwargs. Agno controls session selection and streaming; use Agno session_id and stream arguments rather than native resume flags.
| Fields | Purpose |
|---|---|
model, system_prompt | Choose the model and its instructions. |
tools, allowed_tools, disallowed_tools, permission_mode | Configure tool availability and approval rules. An approval rule is not an exclusive tool allowlist. |
mcp_servers, strict_mcp_config | Provide MCP tools and control loaded server configuration. |
cwd, setting_sources, project_key | Set the working directory, settings sources and stable transcript namespace. |
skills, plugins | Forward native extension configuration. Provision extension files in each execution environment. |
options | Additional typed ClaudeAgentOptions. |
db | Persist Agno records and supported native transcripts. |
output_schema | A Pydantic model or object-root JSON Schema, also overridable per run. |
retries, delay_between_retries, exponential_backoff | Configure agent retries. |
Codex configuration
from agno.agents.codex import CodexAgent
agent = CodexAgent(
id="codex-assistant",
model="gpt-5.6-luna",
instructions="Answer support questions using the configured business tools.",
reasoning_effort="low",
sandbox="read-only",
approval_mode="deny_all",
)Named fields take precedence over option mappings. Prefer thread_options and turn_options to deprecated thread_kwargs and turn_kwargs. Unsupported option names fail explicitly.
| Fields | Purpose |
|---|---|
model, model_provider, reasoning_effort, service_tier | Select provider/model behavior supported by your account. |
instructions, base_instructions | Configure native instructions. |
mcp_servers | Supply tools and their native approval configuration. |
cwd, sandbox, approval_mode | Configure local working directory and execution permissions. |
client_options | A native openai_codex.CodexConfig. |
thread_options, turn_options | Supported typed mappings for native thread/turn options. |
output_schema | A Pydantic model or object-root JSON Schema, also overridable per run. |
ephemeral | Use native threads that are not retained for later native resume. |
db | Persist Agno records and the native thread identity. |
retries, delay_between_retries, exponential_backoff | Configure agent retries. |
Use Agno Image and File inputs for attachments, and output_schema for validated responses. Arbitrary native skill and external-tool-message input objects are not converted into text prompts; use the native SDK for unsupported native input types.
Stream directly in Python
For either adapter:
# With an agent configured above:
result = agent.print_response("Summarize the support policy.", stream=True)
print(result.run_id)In async code use await agent.aprint_response(..., stream=True). The printers return the terminal RunOutput and raise on errors/cancellation by default. Set raise_on_error=False only when your application handles terminal status itself. For programmatic processing, use run() / arun() and inspect the result or events.
Extensions and framework-specific features
Native skills and plugins remain part of the harness configuration. Their files, versions and credentials must be available when execution starts or moves to another environment. Configuring an extension does not persist its installation in the session database.
Claude workspace skills under <cwd>/.claude/skills/ require project settings discovery: set setting_sources=["project"] and make the Skill tool available. setting_sources=[] deliberately disables that discovery; plugin-provided skills can still work. Enable project settings only for workspaces whose configuration you intend to load.
Agno memory, knowledge, learning, hooks and team orchestration are not automatically added to an external harness. Use the integration's supported options and Other Integrations for adapter-specific behavior.