# Implementation Plan 013: Agent Orchestration & ADK Integration

> **Milestone**: 2 — The Generator
> **Tickets**: 2.3 (expanded)

## Objective
Define the standard agent patterns, tool interfaces, and orchestration model for all Ninja Stack agents. This plan covers how agents are structured, how they communicate, and how the Coordinator delegates work.

## Requirements
- **Agent-at-every-level**: Data Agents, Domain Agents, and Coordinators all follow a consistent ADK pattern.
- **Tool-scoped expertise**: Each agent's tools are auto-generated from its ASD domain — it can only access what it owns.
- **Deterministic by default**: Data Agents should not use LLM reasoning unless explicitly configured. Domain Agents use LLM for ambiguity resolution. Coordinators use LLM for routing.
- **Parallel delegation**: Coordinators can fan out to multiple Domain Agents concurrently.
- **Observability**: Every agent invocation is traced (input, tools called, output, latency, cost).

## Agent Types

### Data Agent (Deterministic)
- **Owns**: One entity from the ASD.
- **Tools**: CRUD operations + semantic search (from persistence layer).
- **LLM**: Off by default. Optional for fuzzy matching or natural language filters.
- **Generated by**: `ninjastack sync`.

### Domain Agent (Reasoning)
- **Owns**: A domain (group of entities) from the ASD.
- **Tools**: Delegates to its Data Agents + Graph-RAG traversal.
- **LLM**: On. Handles ambiguous requests, cross-entity reasoning.
- **Generated by**: `ninjastack sync` with user-extensible logic.

### Coordinator Agent (Routing)
- **Owns**: The full project scope.
- **Tools**: Delegates to Domain Agents.
- **LLM**: On. Interprets user intent, plans execution, synthesizes results.
- **Generated by**: `ninjastack sync`.

## Communication Pattern
```
User Request
    │
    ▼
Coordinator Agent
    ├─── (parallel) ──→ Domain Agent A ──→ Data Agent A1
    │                                  ──→ Data Agent A2
    └─── (parallel) ──→ Domain Agent B ──→ Data Agent B1
    │
    ▼
Synthesized Response
```

## Observability
- **Trace ID**: Every request gets a trace ID that flows through all agent hops.
- **Tool call logging**: Every tool invocation is logged with input/output.
- **Cost attribution**: Token usage is attributed to the specific agent and trace.
- **Latency breakdown**: Per-agent and per-tool timing.

## File Structure
```
libs/ninja-agents/
├── pyproject.toml
├── src/ninja_agents/
│   ├── __init__.py
│   ├── base.py               # Base agent classes (Data, Domain, Coordinator)
│   ├── tools.py              # Tool generation from persistence layer
│   ├── orchestrator.py       # Parallel delegation logic
│   ├── tracing.py            # Observability / trace context
│   └── templates/            # ADK agent.yaml templates
└── tests/
```

## Acceptance Criteria
- [ ] A generated Data Agent can perform CRUD via its tools without LLM.
- [ ] A Domain Agent delegates to its Data Agents and reasons over the results.
- [ ] A Coordinator fans out to 2 Domain Agents in parallel and synthesizes.
- [ ] All invocations produce a structured trace log with timing and cost.
- [ ] Agent tool sets are scoped — a Billing agent cannot call Logistics tools.

## Dependencies
- Plan 002 (ASD Core Models — domain and agent definitions)
- Plan 004 (Unified Persistence — tool implementations)
- Plan 011 (LiteLLM — model resolution per agent)
