HTTP API

Route Registration01

The AI extension does not mount routes automatically.

controller := ai.NewAgentController(app.Container())
api := app.Router().Group("/api")
controller.Routes(api)

Registered Routes02

Request and Response Shapes03

Create Agent

POST /agents

{
  "name": "Cache Optimizer",
  "type": "cache_optimizer",
  "model": "gpt-4",
  "temperature": 0.7,
  "config": {}
}

Notes:

• model defaults to gpt-4 if omitted.

• temperature defaults to 0.7 if omitted.

• type must match a built-in template type.

Execute Agent

POST /agents/:id/execute

{
  "message": "Analyze cache hit-rate drop over the last 6 hours"
}

Response includes agent_id and response.

Chat Endpoint

POST /agents/:id/chat

Behavior is currently equivalent to execute (same agent.Execute(...) call path).

List Templates

GET /agents/templates

Returns template identifiers from AgentFactory.ListTemplates().

Error Semantics04

• 400: invalid JSON payload

• 404: missing agent ID

• 500: creation/execution/runtime errors

API Design Notes05

• Agent objects are managed in-memory by AgentManager.

• Delete operation also attempts to remove conversation state from StateStore.

• If you need persistent agent metadata across restarts, store metadata in your own data layer.