Agents

`GET /v1/agents`. Returns all registered profiles. Bypasses the store's read cache because admin-list isn't on the hot path.

`application/json`

curl -X GET "https://example.com/v1/agents"

{  "agents": [    {      "agent_id": "string",      "authority": {        "can_promise": [          "string"        ],        "cannot_promise": [          "string"        ]      },      "display_name": "string",      "escalation_triggers": [        "string"      ],      "knowledge_sources": [        {          "description": "string",          "kb_id": "string",          "kind": "local",          "url": "string"        }      ],      "scope": {        "in_scope": [          "string"        ],        "out_of_scope": [          "string"        ]      },      "system_prompt": "string",      "target_url": "string",      "tone": {        "forbidden": [          "string"        ],        "target": "string"      },      "workflow_definition": null,      "workflow_requirements": [        {          "name": "string",          "required_before": [            "string"          ],          "sensitive_steps": [            "string"          ]        }      ]    }  ]}

`POST /v1/agents` — upsert a profile. Body is YAML (when `Content-Type` is `yaml`) or JSON.

Request Body

application/yaml

Agent profile, YAML or JSON

TypeScript Definitions

Use the request body type in TypeScript.

What an agent is, what it may claim, and how it should sound.

Authored as YAML by the customer (see policies/agents/*.yaml), parsed by tl-policy::load_agent_str, persisted in Postgres, cached in process, and consulted by Tier 2 (out-of-scope embedding lookup) and Tier 3 (LLM judge ground truth).

agent_id*string

authority*

display_name*string

escalation_triggers?array<string>

knowledge_sources?array<>

scope*

system_prompt?|

Raw system prompt the customer ships to their LLM. Source of truth for auto-generating guardrails: POST /v1/agents/{id}/guardrails:generate reads this and asks an LLM to derive a policy set tailored to it. Optional at the type level so existing profiles keep deserializing; the generate endpoint enforces presence at call time.

target_url?|

Loopback endpoint this agent is reachable at (the arena adapter contract), captured at import so the Attacks page can target it without re-typing. Loopback-only; validated at the web edge and by the dispatch SSRF guard.

tone*

workflow_definition?null|

workflow_requirements?array<>

Domain workflows that require checks before sensitive steps are advanced. Hardening uses these as synthesis context after a red-team attack lands.

Response Body

`application/json`

curl -X POST "https://example.com/v1/agents" \  -H "Content-Type: application/yaml" \  -d '<agent_id>string</agent_id>  <authority/>  <display_name>string</display_name>  <scope/>  <tone>    <target>string</target>  </tone>'

{  "agent_id": "string",  "authority": {    "can_promise": [      "string"    ],    "cannot_promise": [      "string"    ]  },  "display_name": "string",  "escalation_triggers": [    "string"  ],  "knowledge_sources": [    {      "description": "string",      "kb_id": "string",      "kind": "local",      "url": "string"    }  ],  "scope": {    "in_scope": [      "string"    ],    "out_of_scope": [      "string"    ]  },  "system_prompt": "string",  "target_url": "string",  "tone": {    "forbidden": [      "string"    ],    "target": "string"  },  "workflow_definition": null,  "workflow_requirements": [    {      "name": "string",      "required_before": [        "string"      ],      "sensitive_steps": [        "string"      ]    }  ]}

`GET /v1/agents/:id`.

Path Parameters

id*string

Agent identifier

Response Body

`application/json`

curl -X GET "https://example.com/v1/agents/string"

{  "agent_id": "string",  "authority": {    "can_promise": [      "string"    ],    "cannot_promise": [      "string"    ]  },  "display_name": "string",  "escalation_triggers": [    "string"  ],  "knowledge_sources": [    {      "description": "string",      "kb_id": "string",      "kind": "local",      "url": "string"    }  ],  "scope": {    "in_scope": [      "string"    ],    "out_of_scope": [      "string"    ]  },  "system_prompt": "string",  "target_url": "string",  "tone": {    "forbidden": [      "string"    ],    "target": "string"  },  "workflow_definition": null,  "workflow_requirements": [    {      "name": "string",      "required_before": [        "string"      ],      "sensitive_steps": [        "string"      ]    }  ]}

`DELETE /v1/agents/:id`. Soft-delete via the store.

Path Parameters

id*string

Agent identifier

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/agents/string"

Empty

`GET /v1/agents/{id}/guardrails` — list active policies owned by an agent. Does not require the agent to exist; missing agent → empty list.

Path Parameters

id*string

Agent identifier

Response Body

`application/json`

curl -X GET "https://example.com/v1/agents/string/guardrails"

{  "policies": [    {      "action": "string",      "description": "string",      "enabled": true,      "family": "content",      "id": "string",      "owner_agent_id": "string",      "severity": "low"    }  ]}

`POST /v1/agents/{id}/guardrails/generate` — derive a set of guardrail policies tailored to an agent's stored `system_prompt`, auto-persist them with `enabled=false`, and return what was saved.

Callers review the set and flip individual policies on via PATCH /v1/policies/{id}/enabled. Runtime checks never see these policies until that happens (because runtime event evaluation filters by enabled).

Path Parameters

id*string

Agent identifier

Response Body

`application/json`

curl -X POST "https://example.com/v1/agents/string/guardrails/generate"

{  "generated": [    {      "description": "string",      "enabled": true,      "family": "content",      "id": "string",      "severity": "low",      "source_yaml": "string"    }  ]}

Agents

200application/json

401application/json

201application/json

400application/json

401application/json

403application/json

422application/json

200application/json

401application/json

404application/json

204

401application/json

403application/json

404application/json

200application/json

401application/json

200application/json

401application/json

404application/json

422application/json

502application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`