Context Engine API

Developer Reference

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

The Context Engine exposes an intent-based REST API. The Platform Framework calls it at runtime; the ADK calls it at registration. Domain teams and external callers never interact with it directly.

Base URL: http://context-engine:8001

Implementation status

This page documents the v4 architecture spec. The running CE API code currently implements 14 endpoints (health, tags, register/*, resolve/{skill, context_builders, agent, tools, tool_class}, list/{skills, tools}). Three additional endpoints are stubbed and return 501 Not Implemented: /search/playbooks, /answer/knowledge, /resolve/domain_knowledge. Endpoints documented here as /resolve/playbook, /resolve/template, /resolve/guardrail, and /answer/rag are part of the v4 design but not yet present in the running API — verify against v4-context-engine/api.py before relying on them in client code.

Design principles

The Context Engine combines vector search (RAG) and graph traversal internally per API call. Callers never know which was used or how they were combined.

Caller:          "give me the skill for this user prompt"
Context Engine:  1. RAG search across Skill collection
                 2. Graph traversal: skill → context builders → guardrails → templates
                 3. Returns enriched skill manifest — one response

RAG and graph are internal implementation details. Every endpoint is intent-based.

Endpoints

Health

`GET /health`

bash

curl http://context-engine:8001/health

json

{ "status": "ok" }

Tag Store

Tags are per-request metadata used to track flow state across multi-phase gateway routing.

`POST /tags/write`

bash

curl -X POST http://context-engine:8001/tags/write \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-abc123",
    "flow": "broad",
    "tags": { "phase": "2c", "domain": "security" }
  }'

Response 201:

json

{
  "request_id": "req-abc123",
  "flow": "broad"
}

Error 409: Tag already exists for request_id. Tags are immutable once written.

`GET /tags/{request_id}`

bash

curl http://context-engine:8001/tags/req-abc123

Response 200:

json

{
  "tags": {
    "request_id": "req-abc123",
    "flow": "broad",
    "tags": { "phase": "2c", "domain": "security" }
  }
}

Error 404: Tag not found or expired. Tags have a short TTL — they are session-scoped.

`DELETE /tags/{request_id}`

bash

curl -X DELETE http://context-engine:8001/tags/req-abc123

Response 204: No content.

Registration (ADK → CE)

These endpoints are called by adk register. They are not called at runtime.

`POST /register/skill`

Registers a skill manifest into the Skill collection. The CE generates embeddings at write time.

bash

curl -X POST http://context-engine:8001/register/skill \
  -H "Content-Type: application/json" \
  -d '{
    "record": {
      "skill_id": "security.detect_public_ingress",
      "domain": "security",
      "display_name": "Detect Public Ingress",
      "purpose": "Detect unrestricted public ingress rules...",
      "description": "Scans security groups and NSGs...",
      "capabilities": ["detect unrestricted inbound access..."],
      "context_descriptions": ["security group ingress rules..."],
      "output_type": "finding",
      "status": "active"
    }
  }'

Response 200:

json

{ "skill_id": "security.detect_public_ingress" }

`POST /register/agent`

bash

curl -X POST http://context-engine:8001/register/agent \
  -H "Content-Type: application/json" \
  -d '{
    "agent_data": { "agent_id": "domain.security.exposure", ... },
    "skill_ids": ["security.detect_public_ingress", "security.detect_public_storage_access"]
  }'

Response 200:

json

{ "agent_id": "domain.security.exposure" }

`POST /register/tool`

bash

curl -X POST http://context-engine:8001/register/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool_data": {
      "tool_id": "aws.ec2.describe_security_groups",
      "tool_class": "network_read",
      "provider": "aws",
      "description": "Lists EC2 security groups and their ingress/egress rules"
    }
  }'

Response 200:

json

{ "tool_id": "aws.ec2.describe_security_groups" }

`POST /register/context_builder`

bash

curl -X POST http://context-engine:8001/register/context_builder \
  -H "Content-Type: application/json" \
  -d '{
    "cb_data": {
      "context_builder_id": "security.public_exposure_context",
      "domain": "security",
      "description": "Builds context for public exposure analysis"
    }
  }'

Response 200:

json

{ "context_builder_id": "security.public_exposure_context" }

Resolution (Platform Framework → CE at runtime)

These endpoints are called by the Gateway and domain agents during request processing.

`POST /resolve/skill`

Resolves a skill by direct ID or by semantic search against the Skill collection.

By skill_id (direct):

bash

curl -X POST http://context-engine:8001/resolve/skill \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": "security.detect_public_ingress",
    "tenant_id": "tenant-xyz"
  }'

Response 200:

json

{
  "skill_id": "security.detect_public_ingress",
  "manifest": { ... },
  "context_builders": [ ... ],
  "guardrails": [ ... ],
  "template": { ... },
  "tools": [ ... ]
}

The CE resolves the skill manifest, traverses the ADK Graph to find all dependencies (context builders, guardrails, templates, tools), and returns the complete enriched package in one response.

By semantic search (when no skill_id is known):

bash

curl -X POST http://context-engine:8001/resolve/skill \
  -H "Content-Type: application/json" \
  -d '{
    "query": "which EC2 instances are exposed to the internet?",
    "tenant_id": "tenant-xyz",
    "top_k": 3
  }'

Response 200:

json

{
  "skills": [
    { "skill_id": "security.detect_public_ingress", "score": 0.94, ... },
    { "skill_id": "security.detect_public_storage_access", "score": 0.71, ... }
  ]
}

Error 404: No matching skill found.

`POST /resolve/agent`

Resolves an agent by semantic search over agent capability embeddings. Used at Phase 2C (miss path) to ground Code Agent in the correct domain boundary.

bash

curl -X POST http://context-engine:8001/resolve/agent \
  -H "Content-Type: application/json" \
  -d '{
    "query": "exposure risks in my network",
    "tenant_id": "tenant-xyz"
  }'

Response 200:

json

{
  "agent_id": "domain.security.exposure",
  "capabilities": [ ... ],
  "owned_skill_ids": [ ... ]
}

`POST /resolve/context`

Resolves context builders for a given skill and tenant.

bash

curl -X POST http://context-engine:8001/resolve/context \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": "security.detect_public_ingress",
    "tenant_id": "tenant-xyz",
    "context_types": ["public_exposure_inventory", "resource_scope_summary"]
  }'

Response 200:

json

{
  "context_builders": [
    {
      "context_builder_id": "security.public_exposure_context",
      "context_type": "public_exposure_inventory",
      "tool_ids": ["aws.ec2.describe_security_groups"],
      "instructions": "..."
    }
  ]
}

`POST /resolve/tools`

Resolves tool metadata for a list of tool_ids.

bash

curl -X POST http://context-engine:8001/resolve/tools \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["aws.ec2.describe_security_groups", "azure.network.list_network_security_groups"]
  }'

Response 200:

json

{
  "tools": [
    { "tool_id": "aws.ec2.describe_security_groups", "tool_class": "network_read", ... },
    { "tool_id": "azure.network.list_network_security_groups", "tool_class": "network_read", ... }
  ]
}

`POST /resolve/tool_class`

Resolves all tools belonging to a tool class.

bash

curl -X POST http://context-engine:8001/resolve/tool_class \
  -H "Content-Type: application/json" \
  -d '{
    "tool_class": "network_read",
    "provider": "aws"
  }'

Error codes

Code	HTTP	Description
`CE-021`	409	Tag already exists for `request_id`
`CE-022`	404	Tag not found or expired
`CE-031`	404	Skill not found (by ID or search returned no results)
`CE-041`	404	Agent not found
`CE-051`	404	Context builder not found
`CE-061`	400	Invalid registration request — schema validation failure

Tenancy model

Every collection search respects tenant precedence:

Search tenant-scoped collection (tenant_id = "tenant-xyz")
Fall back to global collection (tenant_id = null)

Guardrails are the only exception: Both global and tenant guardrails always apply. Tenant guardrails add to global guardrails — they never replace them.

Next steps

Analysis Agent API — The primary Q&A endpoint
Platform Overview — How the CE fits into the execution formula
agent.yaml Reference — What gets registered

Context Engine API ​

Design principles ​

Endpoints ​

Health ​

GET /health ​

Tag Store ​

POST /tags/write ​

GET /tags/{request_id} ​

DELETE /tags/{request_id} ​

Registration (ADK → CE) ​

POST /register/skill ​

POST /register/agent ​

POST /register/tool ​

POST /register/context_builder ​

Resolution (Platform Framework → CE at runtime) ​

POST /resolve/skill ​

POST /resolve/agent ​

POST /resolve/context ​

POST /resolve/tools ​

POST /resolve/tool_class ​

Error codes ​

Tenancy model ​

Next steps ​

Context Engine API

Design principles

Endpoints

Health

`GET /health`

Tag Store

`POST /tags/write`

`GET /tags/{request_id}`

`DELETE /tags/{request_id}`

Registration (ADK → CE)

`POST /register/skill`

`POST /register/agent`

`POST /register/tool`

`POST /register/context_builder`

Resolution (Platform Framework → CE at runtime)

`POST /resolve/skill`

`POST /resolve/agent`

`POST /resolve/context`

`POST /resolve/tools`

`POST /resolve/tool_class`

Error codes

Tenancy model

Next steps