Agent Service

agent-service is the heavy AI service. It runs the DeepAgents engine (a LangGraph loop over an OpenAI-compatible model via @langchain/openai) and streams results as Server-Sent Events (SSE). It also handles PDF parsing, translation, and realtime interview.

• Base URL (dev): http://localhost:3112
• Global prefix: /api
• Swagger UI: /api/docs

Sections

Runtime architecture

Internally agent-service is organized into flat modules:

• runtime — the HTTP entry core (chat / agent / graph controllers) + run lifecycle, SSE writing, per-user daily token budget, trace persistence.
• engine — the DeepAgents engine (the single engine, a LangGraph loop over @langchain/openai); no upper abstraction — runtime / llm / workflows inject the concrete implementation directly.
• llm — assembles prompts → engine streaming, with circuit-breaking / retry (LLM resilience).
• workflows — analyze / research / rewrite workflows + multi-persona analysis.
• interview · translation · document — interview (incl. realtime WebSocket), translation, PDF.

How the engine and harness work (the LangGraph loop, virtual workspace, skills-as-tools, AgentRun→Step→Event persistence) is covered in Engine & harness.

Streaming model

Most agent endpoints respond with Content-Type: text/event-stream. The body is a sequence of frames separated by a blank line; each frame is a single data: line carrying one JSON event:

data: {"type":"run_started","runId":"clx..."}

data: {"type":"message_chunk","content":"Hello","runId":"clx...","stepId":"stp..."}

data: {"type":"done","runId":"clx..."}

Every emitted event carries runId and stepId. The catalog of type values and the parsing rules are in SSE events.

Runs, steps & events (the harness)

Every streamed run is persisted for observability and replay. A run is recorded as AgentRun → AgentStep → AgentEvent. You can fetch a past run after the fact:

This means the runId you see in the stream is a durable handle — store it to later replay or audit what the agent did.

Endpoint map