Analysis Agent API

Developer Reference

This page covers internal implementation details. It is not included in the User Guide.

The Analysis Agent handles factual infrastructure Q&A. It accepts a user query and estate context, reasons over structured data using Claude with tool-assisted computation, and returns a streamed response.

v3 (shipped) vs v4 (designed)

This page documents the shipped v3-analysis-agent-go service, which per its repo README "answers factual questions about AWS infrastructure data using Claude Sonnet" with two modes (standard, broad) and two tools (inspect_schema, compute_stats). The v4 spec describes a richer multi-domain Analysis Agent that emits a structured semantic payload keyed to template blocks via the Context Manager → UI Agent path; that is designed but not yet the live API. Treat the contract here as the v3 surface.

Base URL: http://analysis-agent:8081

Endpoints

`POST /api/v1/analyze`

Accepts an analysis request and returns a Server-Sent Events (SSE) stream.

Headers:

Content-Type: application/json

Request body:

json

{
  "query":      "How many EC2 instances are running in us-east-1?",
  "context":    "<raw JSON string from client>",
  "target":     "H",
  "mode":       "standard",
  "prompt":     { "m": {}, "t": "2026-05-05T12:00:00Z" },
  "profile":    {},
  "id":         "client-device-id",
  "request_id": "req-abc123"
}

Field	Type	Required	Description
`query`	string	Yes*	The user's natural-language question. If empty, extracted from the latest user message in `prompt.m`
`context`	string	Yes	Raw JSON string from the client estate — parsed internally for structured data arrays
`target`	string	Yes	Always `"H"` for this agent. The gateway translates legacy `"br"` to `"H"` + `mode="broad"`
`mode`	string	No	`"standard"` (default) or `"broad"`. Controls which system prompt is used
`prompt`	object	No	Full conversation history. See Conversation History
`profile`	object	No	Profile data passed through to UI Agent for rendering context
`id`	string	No	Client identifier for log correlation
`request_id`	string	No	Request identifier for log correlation

Max body size: 10 MB

`GET /health`

bash

curl http://analysis-agent:8081/health

json

{ "service": "analysis-agent", "status": "healthy" }

Conversation history

The prompt field carries the full conversation history across turns.

json

{
  "m": {
    "0": { "r": 0, "c": "What are my EC2 instances?" },
    "1": { "r": 1, "c": "I found 12 instances in us-east-1." },
    "2": { "r": 0, "c": "How many are running?" }
  },
  "t": "2026-05-05T12:00:00Z"
}

Field	Description
`m`	Message map — keys are message index strings
`m[n].r`	Role: `0` = user, `1` = assistant
`m[n].c`	Content — the message text
`t`	Timestamp of the conversation start

The full conversation history is passed to the UI Agent for coherent multi-turn rendering.

Modes

Mode	System prompt	Behaviour
`standard`	`prompts/analysis-agent-v3.txt`	Full analysis — may include recommendations, findings suggestions
`broad`	`prompts/analysis-agent-broad.txt`	Facts only — plain prose, no recommendations, no findings

broad mode is used for initial estate overview queries where recommendations would be premature.

SSE response events

The response is a stream of Server-Sent Events. Each event has a type and data:

Event type	Description
`text_delta`	Streamed text chunk from the LLM
`tool_use`	The LLM requested a tool call — includes tool name and input
`tool_result`	Result of a tool call — returned to the LLM
`direct_response`	Fallback — plain text response if UI Agent is unavailable
`error`	Error event — includes error code and message
`done`	Stream complete

Example stream:

event: tool_use
data: {"name": "inspect_schema", "input": {"data_key": "ec2_instances"}}

event: tool_result
data: {"result": {"fields": ["id", "type", "state", "region", "tags"], "count": 48}}

event: text_delta
data: {"text": "There are 48 EC2 instances in your estate. "}

event: text_delta
data: {"text": "In us-east-1: 31 instances. Of those, 12 have no Name tag."}

event: done
data: {}

Tools

The Analysis Agent uses two tools internally for structured computation over estate data:

`inspect_schema`

Inspects the schema of a structured data array in the context payload.

json

{
  "name": "inspect_schema",
  "input": {
    "data_key": "ec2_instances"
  }
}

Returns: { "fields": [...], "count": N, "sample": {...} }

The LLM sees metadata — not raw data. This prevents the LLM from reasoning over thousands of raw resource records.

`compute_stats`

Computes aggregate statistics over a structured data array.

json

{
  "name": "compute_stats",
  "input": {
    "data_key": "ec2_instances",
    "group_by": "region",
    "filter": { "state": "running" },
    "metrics": ["count"]
  }
}

Returns: { "groups": { "us-east-1": 31, "us-west-2": 17 }, "total": 48 }

Error handling

HTTP status	Condition
`400`	Malformed request — missing `query` and no messages in `prompt.m`, or invalid JSON
`413`	Request body exceeds 10 MB
`500`	Internal error — LLM call failed, context parsing error
`503`	UI Agent unavailable — falls back to `direct_response` event

Timeout: 120 seconds. Long queries over large estate contexts may approach this limit.

Gateway integration

The gateway routes requests to this agent based on intent classification:

Gateway `target`	Agent	Notes
`"H"` with `mode="standard"`	Analysis Agent	Standard Q&A
`"H"` with `mode="broad"`	Analysis Agent	Facts-only, broad mode
`"br"` (legacy)	Analysis Agent	Translated to `"H"` + `mode="broad"` at gateway

Other target values are routed to different agents (Playbook Agent, Autoresolver, etc.).

Example request (curl)

bash

curl -N -X POST http://analysis-agent:8081/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How many S3 buckets have public read access?",
    "context": "{\"s3_buckets\": [{\"name\": \"prod-logs\", \"acl\": \"public-read\"}, ...]}",
    "target": "H",
    "mode": "standard",
    "request_id": "req-demo-001"
  }'

The -N flag disables curl buffering so SSE events stream in real time.

Next steps

Context Engine API — Knowledge resolution at runtime
Platform Execution Model — How the gateway routes to this agent
Skills Overview — What skill verticals trigger analysis requests

Analysis Agent API ​

Endpoints ​

POST /api/v1/analyze ​

GET /health ​

Conversation history ​

Modes ​

SSE response events ​

Tools ​

inspect_schema ​

compute_stats ​

Error handling ​

Gateway integration ​

Example request (curl) ​

Next steps ​

Analysis Agent API

Endpoints

`POST /api/v1/analyze`

`GET /health`

Conversation history

Modes

SSE response events

Tools

`inspect_schema`

`compute_stats`

Error handling

Gateway integration

Example request (curl)

Next steps