> ## Documentation Index
> Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Reference for the Agent class.

```python theme={null}
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.                         |

## Methods

| 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).                       |

## Run Parameters

| 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. |

## Properties

| 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. |