Agents and Digital Employees Reference

This reference describes the current CodeGraph agent architecture. It intentionally focuses on runtime boundaries and extension points, not on a complete class-by-class API dump. For source-level detail, follow the module map and the public reference documents linked at the end.

Current Mental Model¶

CodeGraph no longer has a single “agent pipeline” as its main architecture. The current system is a set of coordinated planes:

1. Workflow agents route user intent into scenario handlers, CPG queries, domain plugins, and formatted answers.
2. Protocol adapters expose the same capabilities through REST, MCP, ACP, CLI, and headless Codex/OpenCode automation.
3. Digital employees add governed role ownership, task capsules, handoffs, lane evidence, and release-readiness reporting.
4. Context and memory services combine project scope, OpenViking resources, session memory, task memory, story capsules, and repository sync state.
5. Graph intelligence services read CPG facts through GoCPG gRPC at runtime. GoCPG is the writer for project CPG DuckDB files.

flowchart LR
    UI[Frontend / Dashboard] --> API[FastAPI REST]
    Codex[Codex / OpenCode] --> MCP[MCP tools]
    IDE[IDE / ACP client] --> ACP[ACP JSON-RPC / WS / stdio]
    CLI[CLI / headless scripts] --> Services[Application services]

    API --> Services
    MCP --> Services
    ACP --> Services

    Services --> Workflow[Workflow scenarios]
    Services --> Employees[Digital employees]
    Services --> Context[Context and memory]
    Services --> CPG[CPGQueryService]
    Employees --> Tasks[TaskCapsuleService]
    Employees --> Temporal[Temporal coordination]

    CPG --> GoCPG[GoCPG gRPC]
    GoCPG --> DuckDB[(Project CPG DuckDB)]
    Context --> OpenViking[OpenViking]
    Tasks --> AppDB[(Application DB)]
    Temporal --> AppDB

Module Map¶

Workflow Agents¶

Workflow execution is exposed through role-bound digital employee scenario invocation. Runtime callers must use invoke_role_bound_scenario or the corresponding MCP tool with explicit project, namespace, and task scope.

Current workflow code is mixed: some scenarios use the newer handler/formatter registry shape, while some legacy modules still contain composite workflow logic. When adding or materially changing scenario behavior:

• keep intent detection, CPG reads, structured data assembly, and formatting separate;
• prefer BaseHandler plus formatter modules for new handlers;
• preserve benchmark-facing fields such as answer, retrieved_functions, cpg_results, sources, and evidence;
• use domain plugins from src/domains/ for reusable language/framework semantics;
• do not bypass GoCPG/gRPC CPG reads in runtime paths.

The old core helper agents still exist, but they are now one layer inside the larger workflow and governance system:

Digital Employees¶

Digital employees are accountable role lanes, not just prompt personas. The current registry contains 13 role lanes. Together, they provide the governed SDLC contract for development work.

The runtime pattern is:

Anna-owned task plan
    -> named employee task capsules and handoff chain
        -> lane-specific action or tool
            -> evidence refs, artifacts, checks, and events
                -> Anna release-readiness status

Important boundaries:

• TaskCapsuleService is the authoritative task state boundary.
• Handoff lifecycle state is stored through task capsules and events, not a parallel handoff truth store.
• Codex/general AI is an operator that may invoke governed tools; it is not the accountable owner of implementation, review, QA, AppSec, docs, traceability, support, product discovery, or runtime readiness.
• A final “complete” delivery report requires explicit lane evidence or an explicit not-applicable waiver for the required lanes.
• Suggested handoffs are not executed handoffs until the offer/accept/complete lifecycle is recorded.

Key implementation areas:

Protocol Surfaces¶

REST, MCP, and ACP should expose capabilities through shared service/action boundaries.

REST router / MCP tool / ACP handler
    -> shared action or service
        -> context, workflow, digital employee, CPG, or repository service
            -> App DB, OpenViking, GoCPG, Temporal, or external runtime

Rules:

• REST routers validate HTTP shape, auth, rate limits, and project context.
• MCP tools parse tool arguments and call the same actions/services as REST.
• ACP transports and handlers adapt JSON-RPC, WebSocket, stdio, sessions, approvals, hover, diagnostics, and workflow/chat traffic into existing services.
• Frontend code should display backend-authored readiness, reviewability, approval, and chain state instead of inferring governance locally.

Project Scope and Memory¶

Runtime architecture has no global “current project”. Project scope must be explicit, route-bound, workspace-derived, session-bound, or actor-scoped for a user, digital employee, or service account.

Use ProjectContext and ctx.db_path in project-sensitive API, MCP, workflow, automation, and multi-tenant paths. Do not trust user-provided DB paths.

Memory layers:

OpenViking is the primary context backend for repository resources, explicit sessions, memory resources, and native MCP resource access. Project memory and CPG are separate systems; they may be fused for agent context but neither becomes a hidden source of truth for the other.

CPG and Documentation Facts¶

GoCPG owns CPG generation and project CPG DuckDB writes. Runtime reads should go through GoCPG gRPC via CPGQueryService.

Documentation extraction is CPG-first:

• canonical documentation facts come from method_documentation_facts;
• production consumers use CPGQueryService.get_method_documentation_by_identity(...);
• same-name methods in different files must remain distinct;
• legacy name-only comment and description APIs are compatibility/debug surfaces.

Configuration and Limits¶

Use get_unified_config() and attribute access on config objects. Do not hardcode domains, DB paths, limits, thresholds, batch sizes, or timeouts in feature code.

Domain-specific data belongs under src/domains/{domain}/config/ or a reusable domain plugin. Runtime routing and access decisions should use project scope, policy, and backend-authored context.

Extending the System¶

Add or change a workflow scenario¶

1. Review the module map in this reference and the relevant scenario code.
2. Add or update a handler under src/workflow/scenarios/....
3. Use BaseHandler and a formatter when the local scenario supports that pattern.
4. Use CPGQueryService and domain plugins instead of direct DB reads or hardcoded domain knowledge.
5. Add focused tests for the scenario or affected helper.

Add a protocol capability¶

1. Put business logic in a service or shared action.
2. Add thin REST, MCP, or ACP adapters as needed.
3. Keep REST/MCP/ACP parity when the same capability is exposed on more than one surface.
4. Preserve auth, project context, task evidence, rate limiting, and approval gates.

Add or change digital employee behavior¶

1. Start from an Anna-owned plan/task capsule and required lane evidence.
2. Keep role accountability explicit.
3. Write handoff and lifecycle state through task capsules.
4. Use shared employee action modules for REST/MCP/Temporal parity.
5. Do not report full closure until required lane evidence exists.

Validation¶

Run validation that matches the changed surface. Do not run pytest ..

Related Documents¶

• Workflows reference
• API reference
• MCP tools