Appearance
Agent Administration
GhostAI’s agent administration APIs register agent identities per organization. Registered agents are the basis for attributing traffic (for example via X-Agent-Id) on OpenAI- and Anthropic-compatible APIs, policy enforcement, and audit trails.
Registering agents
Create a registration with POST /api/admin/agents (admin-authenticated). Required and optional fields include:
| Field | Notes |
|---|---|
name | Human-readable name (required, length limits apply). |
description | Optional longer text. |
framework | See below; defaults to custom if omitted. |
agent_type | One of: autonomous, semi-autonomous, tool-calling (default). |
Successful registration returns 201 with a server-assigned agent id, organization_id, initial status (typically active), and timestamps.
Framework selection
Set framework to match how the agent was built. Supported values:
| Value | Typical stack |
|---|---|
langchain | LangChain |
crewai | CrewAI |
autogen | AutoGen |
llamaindex | LlamaIndex |
openclaw | OpenClaw / GhostClaw integrations |
custom | In-house or other frameworks |
Agent types
agent_type classifies behavior for policy and reporting:
tool-calling— Primarily invokes tools/APIs when prompted.semi-autonomous— Mixed planning with user or system checkpoints.autonomous— Broader autonomy within configured guardrails.
Use the value that best matches your deployment’s risk review.
Status management
Agent records support a status lifecycle:
| Status | Meaning |
|---|---|
active | Normal operation; identity is valid for attribution and policy checks. |
suspended | Temporarily disabled; use when pausing without deleting history. |
revoked | Permanently withdrawn (see delete behavior below). |
List agents with an optional filter: GET /api/admin/agents?status=active (or suspended / revoked).
Updates use PATCH /api/admin/agents/{agent_id} with partial fields including status.
API reference (CRUD)
Routes are under /api/admin/agents and require admin access.
| Method | Path | Purpose |
|---|---|---|
POST | /api/admin/agents | Register a new agent (201 on success). |
GET | /api/admin/agents | List agents for the org; optional status query. |
GET | /api/admin/agents/{agent_id} | Get one registration. |
PATCH | /api/admin/agents/{agent_id} | Update name, description, framework, type, or status. |
DELETE | /api/admin/agents/{agent_id} | Revoke the agent (sets status to revoked). |
DELETE returns 204 No Content
DELETE /api/admin/agents/{agent_id} responds with 204 and no response body. Clients should treat 204 as success and refresh lists or local state from a subsequent GET if they need the updated record.
Deletion semantics in the API mark the agent as revoked (soft revoke) while preserving the row for audit continuity—confirm behavior in your environment if you rely on hard deletes.