Agent loop
The agent loop is the core turn cycle: receive message, assemble context, call the LLM, execute tools, stream or finalize the reply.
sequenceDiagram
participant Ch as Channel adapter
participant R as Gateway router
participant O as Orchestrator
participant A as CarinaAgent
participant L as LLM
participant T as Tool runner
Ch->>R: Inbound message
R->>O: Resolve session + workspace
O->>A: turn(input)
A->>L: Chat completion (tools optional)
L-->>A: Text and/or tool calls
A->>T: Execute tools (policy gated)
T-->>A: Tool results
A->>L: Follow-up completion (if needed)
A-->>O: Assistant message
O-->>Ch: Outbound format
Steps in one turn
- Session resolution - Map channel identity to a stable session key (
gateway/router.ts). - Context build - System prompt, memory hits, skills, channel metadata (
agents/system-prompt.ts, memory modules). - LLM call - Provider selected from config or workspace profile (
brain/llm.ts). - Tool execution - Registry dispatches tools; Scout and sequence guards may block or confirm (
tools/,security/). - Response delivery - Formatting per channel (markdown subset, streaming edits, etc.).
Where to find it in source
| Piece | Path under core.carinaai.uk/src/ |
|---|---|
| Orchestrator entry | agents/orchestrator.ts |
| Single turn | agents/carina.ts (CarinaAgent.turn) |
| Tool dispatch | agents/tool-runner.ts (or equivalent in orchestrator wiring) |
| Gateway routing | gateway/router.ts |