Skip to content

feat: implement AgentEngine core orchestrator (#11) #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Aureliolo wants to merge 2 commits into from
Closed

feat: implement AgentEngine core orchestrator (#11) #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff9cbfd
feat: implement AgentEngine core orchestrator (#11)
Aureliolo Mar 6, 2026
b033a75
feat: implement AgentEngine core orchestrator (#11)
Aureliolo Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ src/ai_company/
communication/ # Inter-agent message bus and channels
config/ # YAML company config loading and validation
core/ # Shared domain models and base classes
engine/ # Agent execution engine and task lifecycle
engine/ # Agent orchestration, execution loops, and task lifecycle
memory/ # Persistent agent memory (memory layer TBD)
observability/ # Structured logging, correlation tracking, log sinks
providers/ # LLM provider abstraction (LiteLLM adapter)
Expand Down
31 changes: 31 additions & 0 deletions DESIGN_SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -911,6 +911,36 @@ hybrid:

> **Auto-selection (optional):** When `execution_loop: "auto"`, the framework selects the loop based on `estimated_complexity`: simple → ReAct, medium → Plan-and-Execute, complex/epic → Hybrid. Configurable via `auto_loop_rules` — a mapping of complexity thresholds to loop implementations (e.g., `{simple_max_tokens: 500, medium_max_tokens: 3000}` with corresponding loop assignments).

#### AgentEngine Orchestrator

`AgentEngine` (in `engine/agent_engine.py`) is the top-level entry point for running an agent on a task. It composes the execution loop with prompt construction, context management, tool invocation, and cost tracking into a single `run()` call.

**`run(identity, task, completion_config?, max_turns?) -> AgentRunResult`**

Pipeline steps:

1. **Validate inputs** — agent must be `ACTIVE`, task must be `ASSIGNED` or `IN_PROGRESS`. Raises `ExecutionStateError` on violation.
2. **Build system prompt** — calls `build_system_prompt()` with agent identity, task, and available tool definitions.
3. **Create context** — `AgentContext.from_identity()` with the configured `max_turns`.
4. **Seed conversation** — injects system prompt and formatted task instruction as initial messages.
5. **Transition task** — `ASSIGNED` → `IN_PROGRESS` (pass-through if already `IN_PROGRESS`).
6. **Prepare tools and budget** — creates `ToolInvoker` from registry and `BudgetChecker` from task budget limit.
7. **Delegate to loop** — calls `ExecutionLoop.execute()` with context, provider, tool invoker, budget checker, and completion config.
8. **Record costs** — records accumulated `TokenUsage` to `CostTracker` (if available). Cost recording failures are logged but do not affect the result.
9. **Return result** — wraps `ExecutionResult` in `AgentRunResult` with engine-level metadata.

Error handling: `MemoryError` and `RecursionError` propagate unconditionally. All other exceptions are caught and wrapped in an `AgentRunResult` with `TerminationReason.ERROR`.

Constructor accepts: `provider` (required), `execution_loop` (defaults to `ReactLoop`), `tool_registry`, `cost_tracker`.

**`AgentRunResult`** — frozen Pydantic model wrapping `ExecutionResult` with engine metadata:

- `execution_result` — outcome from the execution loop
- `system_prompt` — the `SystemPrompt` used for this run
- `duration_seconds` — wall-clock run time
- `agent_id`, `task_id` — identifiers
- Computed fields: `termination_reason`, `total_turns`, `total_cost_usd`, `is_success`

### 6.6 Agent Crash Recovery

When an agent execution fails unexpectedly (unhandled exception, OOM, process kill), the framework needs a recovery mechanism. Recovery strategies are implemented behind a `RecoveryStrategy` protocol, making the system pluggable — new strategies can be added without modifying existing ones.
Expand Down Expand Up @@ -2122,6 +2152,7 @@ ai-company/
│ │ ├── context.py # AgentContext + AgentContextSnapshot
│ │ ├── loop_protocol.py # ExecutionLoop protocol + result models
│ │ ├── react_loop.py # ReAct loop implementation
│ │ ├── run_result.py # AgentRunResult outcome model
│ │ ├── agent_engine.py # Agent execution engine (M3)
Comment on lines +2155 to 2156
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Section 15.3 now contradicts itself.

The note above this tree says milestone-tagged files are planned-only, but agent_engine.py is still tagged (M3) even though this PR adds it. Please either drop milestone tags from shipped files or rewrite the note so readers can tell which engine modules actually exist.

Based on learnings, "When making changes that affect architecture, services, key files, settings, or workflows, update the relevant sections of existing documentation (CLAUDE.md, README.md, etc.) to reflect those changes."

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@DESIGN_SPEC.md` around lines 2155 - 2156, Section 15.3's "planned-only" note
conflicts with the file tree because agent_engine.py is listed with a milestone
tag (M3) but the PR actually adds that file; update the doc so readers can tell
which modules exist now by either removing milestone tags from files that are
already shipped (remove "(M3)" from agent_engine.py and any other added files
like run_result.py if shipped) or rewrite the note to state that milestone tags
indicate original plan (not current presence) and explicitly mark planned-only
files (e.g., add "(planned)" or a separate subsection). Also update any
cross-references mentioned (CLAUDE.md, README.md) to reflect the corrected
status of agent_engine.py and related engine modules.

│ │ ├── task_engine.py # Task routing & scheduling (M3-M4)
│ │ ├── workflow_engine.py # Workflow orchestration (M4)
Expand Down
4 changes: 4 additions & 0 deletions src/ai_company/engine/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
runtime execution state, execution loops, and engine errors.
"""

from ai_company.engine.agent_engine import AgentEngine
from ai_company.engine.context import (
DEFAULT_MAX_TURNS,
AgentContext,
Expand Down Expand Up @@ -31,6 +32,7 @@
build_system_prompt,
)
from ai_company.engine.react_loop import ReactLoop
from ai_company.engine.run_result import AgentRunResult
from ai_company.engine.task_execution import StatusTransition, TaskExecution
from ai_company.providers.models import ZERO_TOKEN_USAGE, add_token_usage

Expand All @@ -39,6 +41,8 @@
"ZERO_TOKEN_USAGE",
"AgentContext",
"AgentContextSnapshot",
"AgentEngine",
"AgentRunResult",
"BudgetChecker",
"BudgetExhaustedError",
"DefaultTokenEstimator",
Expand Down
Loading