# 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.

```json
{
  "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`.

```json
{
  "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`.

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

Returns `202 Accepted` with a [Run](runs.html). 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](runs.html).