Agents API — Configurator

The Agents API manages agents: an LLM, a prompt, tools, skills, knowledge, guardrails, and optional sub-agents combined into a versioned, deployable configuration that ADK runs. For architecture and configuration, see Configurator.

Paths are relative to the Configurator service root (port 8100 locally). Authentication, required headers, errors, and the pagination envelope follow the API conventions; see Pagination for page and page_size (default 20, maximum 100).

When a request sends X-Project-Id, list and bulk-fetch results only include agents enabled in that project, and detail routes return 404 for agents that are not enabled. New agents are bound to the project; if binding fails, the creation is rolled back.

Endpoints

There is no PATCH and no clone route.

Create or Update an Agent

POST /api/v1/agents/ and PUT /api/v1/agents/{id}/

Configuration fields

Read-only fields: version, status, content_hash, topology_hash, and business_events (deprecated; replaced by analyzers, with a business_events_deprecated flag in the output).

curl -s -X POST 'http://localhost:8100/api/v1/agents/' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Org-Id: YOUR_ORG_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "customer_support_agent",
    "description": "Handles customer support inquiries",
    "configuration": {
      "type": "llm",
      "model": {"provider": "azure_openai", "model": "gpt-4o"},
      "prompt": "You are a helpful customer support agent.",
      "tools": [{"id": "TOOL_ID", "type": "api", "version": "1.0"}]
    }
  }'

The response is the agent (id, org_id, name, description, tags, timestamps) with latest_draft and latest_deployed configurations.

Versioning

Versions are major.minor strings. On update:

Each new configuration emits agent.configuration.added or agent.configuration.updated on the configurator Kafka topic.

List Agents

GET /api/v1/agents/

List Versions

GET /api/v1/agents/{id}/versions/

Deploy

POST /api/v1/agents/{id}/deploy/

Takes no body. Deploys the agent's latest draft and also deploys any draft sub-agents it references. Returns 400 when there is no draft. ADK and the other consumers receive agent.configuration.deployed.

Delete

DELETE /api/v1/agents/{id}/ soft-deletes the agent and returns 204. Deletion is blocked while the agent is used as a sub-agent, a graph node, or an app's orchestrator. Consumers receive agent.deleted.

Bulk Fetch

GET /api/v1/agents/bulk-fetch/?agent=<uuid>&agent=<uuid>:2.1

Each agent value is either a UUID (latest deployed configuration; returned with configuration: null when nothing is deployed) or uuid:version (that exact version; omitted when it does not exist). Malformed UUIDs and empty versions (uuid:) return 400.

Authorized Search

GET /api/v1/agents/authorized-search/?app_id=...&scope_type=...&scope_id=...

Takes the list filters plus app_id, scope_type, scope_id (all required), and action (default agent.execute). Returns only the agents the caller may run in that scope.

Tree

GET /api/v1/agents/{id}/tree/?version=1.0 returns the agent and its resolved sub-agents for the given version.

Running Agents

Deployed agents run on ADK, not Configurator. Use the ADK host with /api/v1/adk/converse/ (sync), /api/v1/adk/converse/v2 (WebSocket), or /api/v1/adk/async/requests/ (async). See the ADK Converse API.

Related APIs

• Tools API: tools that agents use
• Apps API: apps that expose agents to end users
• ADK Converse API: agent execution