Agents API

The Agents API lets an API Client discover published Eos Agents and start a run. It does not expose the Agent editor, unpublished drafts, compilation controls, schedules, or internal prompt implementation.

Effective authorization

An Agent's configured capabilities are an upper bound, not a grant. Every tool call made during a run must pass all of these checks:

1. The Agent is published and permits the api_client principal type.
2. The API Client's license level makes the required skill available.
3. The API Client has every Eos Role required by that skill and operation.
4. The target resource, field, workflow state, and integration connection allow the operation.
5. If a member subject is supplied, the skill explicitly supports subject context.

The API Client remains the actor for the entire run. A subject describes whom the work concerns; it does not add the member's Roles, project membership, personal connection, or identity.

List and get Agents

• GET /v1/agents — listAgents
• GET /v1/agents/{agent_id} — getAgent

Only published Agents visible to this API Client are returned.

{
  "object": "agent",
  "id": "agt_01J8RF2Z3TYMRYQYZPX0K83FWP",
  "name": "Invoice follow-up agent",
  "description": "Prepares follow-up activity for overdue invoices.",
  "status": "published",
  "accepted_principal_types": ["named_user", "api_client"],
  "required_roles": ["finance"],
  "supports_subject": false,
  "input_schema": {
    "type": "object",
    "properties": {"invoice_id": {"type": "string"}},
    "required": ["invoice_id"]
  },
  "output_schema": {"type": "object"},
  "version": "7"
}

Check readiness

POST /v1/agents/{agent_id}/readiness

Operation ID: checkAgentReadiness.

{
  "input": {"invoice_id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S"}
}

The response reports whether the Agent can be started by this client and lists safe, machine-readable blockers such as a missing Role, unsupported principal type, unavailable skill, or disconnected organization integration. Readiness is advisory; authorization is evaluated again during the run.

Start an Agent run

POST /v1/agents/{agent_id}/runs

Operation ID: createAgentRun. Required header: Idempotency-Key.

{
  "input": {"invoice_id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S"},
  "subject": null,
  "metadata": {"external_job_id": "job-8821"}
}

Returns 202 Accepted with a Run. Supplying subject is valid only if the Agent and every subject-dependent skill in the execution path support it. member_id is the member's normalized email address and must exactly match an active member in the API Client's organization.

Human interaction and approvals

A run can enter requires_action for clarification or an explicitly low-risk confirmation defined by the Agent. It cannot ask the API Client to impersonate a human approver. Formal approvals remain named-user actions and cannot be completed by an API Client run.

Common errors

AGENT_NOT_FOUND, AGENT_NOT_PUBLISHED, API_PRINCIPAL_NOT_SUPPORTED, LICENSE_LEVEL_REQUIRED, ROLE_REQUIRED, SUBJECT_NOT_SUPPORTED, AGENT_INPUT_INVALID, and INTEGRATION_CONNECTION_NOT_READY.

Next: Runs API.