# Agent
The central entity in the system. An Agent combines a given identity (Agent Profile), capabilities (tools, skills, MCP connections), permissions, and introspection into a single runtime unit that executes Sessions (tasks).
The `Agent` trait defines the runtime interface (prompting, state access, control, steering queues). `BasicAgent` is the default in-memory implementation that owns conversation state, tools, and provider configuration.
## Concept Overview
```
Agent
├── HEADER
│ ├── agent_id [EXISTS] — UUID, immutable
│ ├── Agent Profile [EXISTS] — AgentProfile struct (src/agents/profile.rs)
│ │ ├── profile_id [EXISTS] — distinct from agent_id; shareable across agents
│ │ ├── SystemPromptStrategy [EXISTS] — how system prompt is composed
│ │ │ └── static system_prompt string [EXISTS], file: prefix [EXISTS], {{...}} 3-entity chain [EXISTS]
│ │ ├── Agent Name [EXISTS] — Option<String> on AgentProfile
│ │ └── Agent Description [EXISTS] — Option<String> on AgentProfile
│ ├── Limits (Agent-level)
│ │ ├── context_config [EXISTS]
│ │ ├── execution_limits [EXISTS]
│ │ └── retry_config [EXISTS]
│ └── Default Model [EXISTS — BasicAgent.model_config]
│ └── Fallback when Session and Loop don't specify their own
│
├── TAB: Sessions (Tasks) [EXISTS]
│ └── (drill-down: Session → Loop → Turn)
├── TAB: Capabilities [EXISTS as Vec<Arc<dyn AgentTool>>]
│ ├── Tools [EXISTS] ├── Sub-agents [EXISTS]
│ ├── OpenAPI tools [EXISTS] └── Built-in tools [EXISTS]
├── TAB: Skills [EXISTS as SkillSet; CONCEPTUAL as browsable tab]
├── TAB: MCP Connections [EXISTS]
├── TAB: Permissions [CONCEPTUAL]
│ ├── Include rules [CONCEPTUAL] └── Exclude rules [CONCEPTUAL]
├── TAB: Introspection [CONCEPTUAL] — mandatory when scope = Persistent
│ ├── Episodic Memory [CONCEPTUAL] ├── Semantic Memory [CONCEPTUAL]
│ ├── Procedural Memory [CONCEPTUAL]
│ ├── Identity Shaping └── Knowledge Base
│
└── STATE (runtime) [EXISTS]
├── session_id [EXISTS] ├── messages [EXISTS]
├── queues [EXISTS] └── counters [EXISTS]
```
---
## HEADER
| `agent_id` | `String` (UUID v4) | `[EXISTS]` | Stable identifier assigned at construction. Included in every `AgentStart` event. Immutable for the lifetime of the agent instance. |
| **Agent Profile** | `AgentProfile` | `[EXISTS]` | Reusable identity blueprint (`src/agents/profile.rs`). Separate struct from Agent — multiple agents can share one profile via config instances. Fields: profile_id, name, description, system_prompt, thinking_level, temperature, max_tokens, config_id, skills, workspace. |
| `profile_id` | `String` | `[EXISTS]` | Distinct from `agent_id`. Allows profile sharing across agents. Auto-generated UUID if not set. |
| `SystemPromptStrategy` | trait | `[EXISTS]` | Defines block structure for multi-block prompt composition (`src/agents/system_prompt.rs`). Uses a 3-entity model: **strategy template** (block definitions with order + max_length), **prompt instance** (content filling blocks, supports `file:` paths), **agent reference** (via `{{system_prompt.name}}`). See [configuration guide](../../guides/configuration.md#system-prompt-strategy). |
| `system_prompt` | `Option<String>` | `[EXISTS]` | System prompt string. Lives on `AgentProfile.system_prompt`. Supports inline text, `file:path` (relative to workspace), or `{{...}}` reference to a prompt instance. Resolution: agent > profile instance > base profile. |
| Agent Name | `Option<String>` | `[EXISTS]` | Human-readable name. Lives on `AgentProfile.name`. |
| Agent Description | `Option<String>` | `[EXISTS]` | Description of the agent's purpose. Lives on `AgentProfile.description`. |
| `workspace` | `Option<PathBuf>` | `[EXISTS]` | Working directory. Lives on `AgentProfile` as blueprint default; `BasicAgent` stores an agent-level override. Resolution: agent workspace > profile workspace > current directory. |
| `model_config` | `ModelConfig` | `[EXISTS]` | Default model for this agent. Falls back here when Session and Loop don't specify their own. Contains: model id, API key, base URL, API protocol, cost rates, context window size. |
| `context_config` | `Option<ContextConfig>` | `[EXISTS]` | Token budget and compaction policy. Agent-level limit. |
| `execution_limits` | `Option<ExecutionLimits>` | `[EXISTS]` | Max turns (50), max tokens (1M), max duration (10 min), cost tracking. Agent-level limit. |
| `retry_config` | `RetryConfig` | `[EXISTS]` | Retry policy for provider errors. Exponential backoff with jitter. Agent-level. |
| `cache_config` | `CacheConfig` | `[EXISTS]` | Prompt caching behavior (enabled/disabled, strategy: Auto/Disabled/Manual). |
| `tool_execution` | `ToolExecutionStrategy` | `[EXISTS]` | How tool calls are executed: Parallel (default), Sequential, Batched. |
| `thinking_level` | `ThinkingLevel` | `[EXISTS]` on Agent | Controls depth of model reasoning (Off/Minimal/Low/Medium/High). Agent default; per-loop values tracked in `LoopConfigSnapshot`. |
| `temperature` | `Option<f32>` | `[EXISTS]` on Agent | Sampling temperature. Agent default; per-loop values tracked in `LoopConfigSnapshot`. |
| `max_tokens` | `Option<u32>` | `[EXISTS]` | Max output tokens per response. None = use model default. |
| `provider_override` | `Option<Arc<dyn StreamProvider>>` | `[EXISTS]` | Escape hatch for test injection or custom providers. Bypasses `ProviderRegistry` dispatch. |
---
## TAB: Sessions (Tasks) `[EXISTS]`
Sessions are the actions an agent performs. Each Session contains Loops (iterations) which contain Turns (steps). See [session.md](session.md).
| `session_id` | `String` (UUID v4) | `[EXISTS]` | Current session identifier. Rotatable via `check_and_rotate`. |
---
## TAB: Capabilities `[EXISTS]`
Registered tools available to the agent. Stored as `Vec<Arc<dyn AgentTool>>`.
| Tools | `[EXISTS]` | Registered `AgentTool` implementations. Added via `with_tools()`. |
| Sub-agents | `[EXISTS]` | Via `SubAgentTool`. Spawns child agent loops in separate sessions. |
| OpenAPI tools | `[EXISTS]` | Auto-generated from OpenAPI 3.0 spec via `OpenApiToolAdapter`. Feature-gated (`openapi`). |
| Built-in tools | `[EXISTS]` | Bash, File, Edit, Grep, ListDir, ReadFile. |
---
## TAB: Skills `[EXISTS]` as SkillSet; `[CONCEPTUAL]` as browsable tab
Declarative capabilities loaded from `SKILL.md` files with YAML frontmatter.
| `SkillSet` | `[EXISTS]` | Loaded via `with_skills()`. Discovery and loading from filesystem. |
| Skill discovery | `[EXISTS]` | Finds `<name>/SKILL.md` files. |
| Skill browsing / editing | `[CONCEPTUAL]` | Interactive skill management in a UI. |
---
## TAB: MCP Connections `[EXISTS]`
Model Context Protocol integration for external tool servers.
| MCP server connections | `[EXISTS]` | Stdio and HTTP transports via `McpClient` / `McpTransport`. |
| Discovered tools | `[EXISTS]` | Auto-registered from MCP server via `McpToolAdapter`. Transparent to agent loop. |
| MCP connection management | `[CONCEPTUAL]` | Browsable tab for managing connections in a UI. |
---
## TAB: Permissions `[CONCEPTUAL]`
Access control for agent actions. Not yet implemented.
| Include rules | `[CONCEPTUAL]` | Whitelist of allowed actions. |
| Exclude rules | `[CONCEPTUAL]` | Blacklist of denied actions. |
---
## TAB: Introspection `[CONCEPTUAL]`
Memory extraction from session logs and identity. Mandatory when Session scope is Persistent.
### Memory Categories
| Episodic Memory | `[CONCEPTUAL]` | What happened in past sessions (events, conversations). |
| Semantic Memory | `[CONCEPTUAL]` | Distilled knowledge (facts, concepts, relationships). |
| Procedural Memory | `[CONCEPTUAL]` | Successful strategies learned over time (patterns, playbooks). |
### Memory Destinations
| Identity Shaping | `[CONCEPTUAL]` | Memory feeds back to evolve the Agent Profile. |
| Knowledge Base | `[CONCEPTUAL]` | Searchable database for future use. |
---
## Agent State (Runtime) `[EXISTS]`
Mutable state that changes during execution.
| `session_id` | `String` | `[EXISTS]` | Current session. Rotatable via `check_and_rotate` on inactivity timeout. |
| `messages` | `Vec<AgentMessage>` | `[EXISTS]` | Full conversation history (LLM + Extension messages). |
| `steering_queue` | `Arc<Mutex<Vec<AgentMessage>>>` | `[EXISTS]` | Mid-run interrupt messages. Drained per `steering_mode` (OneAtATime / All). |
| `follow_up_queue` | `Arc<Mutex<Vec<AgentMessage>>>` | `[EXISTS]` | Post-turn follow-up messages. Drained per `follow_up_mode`. |
| `loop_counters` | `HashMap<String, usize>` | `[EXISTS]` | Per-(session, config) monotonic counters for loop ID generation. |
| `last_loop_id` | `Option<String>` | `[EXISTS]` | Most recently started loop. Used for `parent_loop_id` in continuations. |
| `last_active_at` | `Option<DateTime<Utc>>` | `[EXISTS]` | Timestamp of last prompt call. Used by `check_and_rotate` for inactivity detection. |
| `cancel` | `Option<CancellationToken>` | `[EXISTS]` | Abort handle. `Some` during streaming, `None` otherwise. |
| `is_streaming` | `bool` | `[EXISTS]` | Guard against concurrent `prompt()` calls. |
| `session` | `Option<Session>` | `[EXISTS]` | Optional session for block-based compaction. |
---
## Code Reference
| `src/agents/agent.rs` | `Agent` trait — runtime interface (~40 methods: prompting, state, control, steering queues, hook setters). `QueueMode` enum. |
| `src/agents/basic_agent.rs` | `BasicAgent` struct — default in-memory implementation. Builder pattern. All fields listed above. |
| `src/agents/profile.rs` | `AgentProfile` struct — reusable identity blueprint with profile_id, name, description, system_prompt, thinking_level, temperature, max_tokens, config_id, skills, workspace. |
| `src/agents/system_prompt.rs` | `SystemPromptStrategy` trait, `SystemPrompt` struct, `PromptBlockDef`, built-in strategies (Custom, Agent, Minimal). Compose logic with `file:` resolution. |
---
## Conceptual Notes
- **Agent Profile as a separate struct** does not exist in code. The `system_prompt` field lives directly on `BasicAgent`. A future `AgentProfile` struct would hold `profile_id`, `SystemPromptStrategy`, name, and description, enabling profile sharing across agents.
- **SystemPromptStrategy** now exists as a trait with a `compose(context) -> String` method. It follows a 3-entity model: **strategy template** (the trait implementation), **prompt instance** (concrete prompt for a given context), **profile ref** (agent profile reference). Full 5-layer composition (base personality, task context, tool/skill index, memory context, turn-specific instructions) is future work. `BasicAgent` retains a static `system_prompt` string as a fallback.
- **thinking_level and temperature** are Agent-level defaults. Per-loop values are captured in `LoopConfigSnapshot` on each `LoopRecord`. `AgentProfile::resolve_thinking_level()` and `resolve_temperature()` have been removed; resolution is now direct from `AgentLoopConfig`.
- **Introspection** is the largest conceptual gap. It requires session log analysis, memory categorization (episodic/semantic/procedural), and feedback loops to Agent Profile evolution.