Agent

from definable.agent import Agent

Constructor

Parameter	Type	Default	Description
`model`	`str \| Model`	—	LLM provider. String shorthand (`"gpt-4o"`) or Model instance.
`instructions`	`str`	`""`	System prompt instructions.
`tools`	`List[Function]`	`[]`	Tool functions decorated with `@tool`.
`toolkits`	`List[Toolkit]`	`[]`	Toolkit instances (MCPToolkit, BrowserToolkit).
`skills`	`List[Skill]`	`[]`	Skill instances (instructions + tools).
`knowledge`	`Knowledge \| str`	`None`	RAG knowledge base or directory path shorthand.
`memory`	`Memory \| bool`	`None`	Session memory. `True` for InMemoryStore.
`thinking`	`Thinking \| bool`	`None`	Reasoning phase. `True` for defaults.
`deep_research`	`DeepResearchConfig \| bool`	`None`	Multi-wave research. `True` for defaults.
`audio_transcriber`	`AudioTranscriber \| bool`	`None`	Voice transcription. `True` for Whisper.
`security`	`SecurityConfig \| bool`	`None`	Security hardening. `True` for defaults.
`guardrails`	`Guardrails`	`None`	Input/output/tool guardrails.
`middleware`	`List[Middleware]`	`[]`	Middleware chain.
`tracing`	`Tracing \| bool`	`None`	Event export. `True` for DebugExporter.
`plugins`	`List[Plugin]`	`None`	Plugins loaded on first `arun()`.
`readers`	`BaseReader \| bool`	`None`	File readers. `True` for auto-registry.
`config`	`AgentConfig`	`AgentConfig()`	Execution configuration.
`usage`	`UsageTracker \| bool`	`None`	Token/cost tracking. `True` for defaults.
`name`	`str`	`None`	Display name (overrides `config.agent_name`).
`debug`	`bool`	`False`	Color-coded turn-by-turn debug output.

Method	Returns	Description
`run(instruction, **kwargs)`	`RunOutput`	Synchronous execution.
`arun(instruction, **kwargs)`	`RunOutput`	Async execution.
`run_stream(instruction, **kwargs)`	`Iterator[RunOutputEvent]`	Sync streaming.
`arun_stream(instruction, **kwargs)`	`AsyncIterator[RunOutputEvent]`	Async streaming.
`serve(interfaces, *kwargs)`	—	Start runtime with interfaces, webhooks, cron.
`aserve(interfaces, *kwargs)`	—	Async version of serve.
`replay(run_output=, trace_file=)`	`Replay \| RunOutput`	Inspect or re-execute a past run.
`compare(a, b)`	`ReplayComparison`	Compare two runs.
`security_audit()`	`SecurityReport`	Run security audit.
`use(middleware)`	`Agent`	Add middleware (fluent).

Parameter	Type	Default	Description
`instruction`	`str`	—	User message.
`messages`	`List[Message]`	`None`	Existing conversation history.
`session_id`	`str`	`None`	Session grouping identifier.
`run_id`	`str`	`None`	Unique run identifier.
`user_id`	`str`	`None`	User identifier for memory scoping.
`images`	`List[Image]`	`None`	Image inputs.
`audio`	`List[Audio]`	`None`	Audio inputs.
`videos`	`List[Video]`	`None`	Video inputs.
`files`	`List[File]`	`None`	File inputs.
`output_schema`	`Type[BaseModel]`	`None`	Pydantic model for structured output.

Property	Type	Description
`agent_id`	`str`	Unique identifier.
`agent_name`	`str`	Display name.
`tool_names`	`List[str]`	Registered tool names.
`plugin_registry`	`PluginRegistry`	Plugin manager.
`usage_tracker`	`UsageTracker \| None`	Token/cost tracker.
`scheduler`	`Scheduler \| None`	Auto-created scheduler for triggers.