> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API: Create and Manage AI Agents

> Create, update, and delete agents with the OneCLI API. Manage gateway access tokens, hosted agent models, avatars, conversations, and SSH access.

An agent is an identity the gateway recognizes by its access token. It can run on your own machine and route through the gateway, or run as a hosted agent with its own sandbox.

Use these endpoints to provision agents, rotate their tokens, and configure hosted agents. To decide which credentials an agent may use, see the [Grants](https://onecli.sh/docs/api-reference/grants) endpoints and [Agent access](https://onecli.sh/docs/guides/agent-access.md).

## Related guides

* [Agent access: grant credentials to agents](https://onecli.sh/docs/guides/agent-access.md)
* [Coding agents: route your agent through OneCLI](https://onecli.sh/docs/guides/coding-agents.md)
* [How it works: the gateway and agent tokens](https://onecli.sh/docs/how-it-works.md)

## Endpoints

| Endpoint | Method and path | What it does |
| - | - | - |
| [List agents](https://onecli.sh/docs/api-reference/agents/list-agents.md) | `GET /agents` | List every agent in your workspace, newest first, with its gateway access token. |
| [Create an agent](https://onecli.sh/docs/api-reference/agents/create-an-agent.md) | `POST /agents` | Create an agent in your workspace, either one you run yourself through the gateway or a hosted agent. |
| [Get an agent](https://onecli.sh/docs/api-reference/agents/get-an-agent.md) | `GET /agents/{agentId}` | Get one agent with its hosted configuration, such as harness, model, and instructions. |
| [Update an agent](https://onecli.sh/docs/api-reference/agents/update-an-agent.md) | `PATCH /agents/{agentId}` | Rename an agent, or change a hosted agent's brief and model override. |
| [Delete an agent](https://onecli.sh/docs/api-reference/agents/delete-an-agent.md) | `DELETE /agents/{agentId}` | Delete an agent with its grants, conversations, schedules, memories, and channel presences. |
| [Regenerate an agent's access token](https://onecli.sh/docs/api-reference/agents/regenerate-an-agents-access-token.md) | `POST /agents/{agentId}/regenerate-token` | Mint a new gateway access token for an agent and invalidate the old one. |
| [Restart a hosted agent](https://onecli.sh/docs/api-reference/agents/restart-a-hosted-agent.md) | `POST /agents/{agentId}/restart` | Restart a hosted agent. |
| [List an agent's available models](https://onecli.sh/docs/api-reference/agents/list-an-agents-available-models.md) | `GET /agents/{agentId}/models` | List the models an agent's granted LLM key can run, the provider defaults, and the agent's current selection. |
| [Upload an agent's avatar](https://onecli.sh/docs/api-reference/agents/upload-an-agents-avatar.md) | `PUT /agents/{agentId}/image` | Upload an agent's avatar as raw PNG, JPEG, GIF, or WebP bytes up to 1 MB. |
| [Remove an agent's avatar](https://onecli.sh/docs/api-reference/agents/remove-an-agents-avatar.md) | `DELETE /agents/{agentId}/image` | Remove an agent's avatar and return it to the default mark. |
| [Open your direct conversation with an agent](https://onecli.sh/docs/api-reference/agents/open-your-direct-conversation-with-an-agent.md) | `PUT /agents/{agentId}/conversations/direct` | Open your private direct conversation with an agent, creating it on the first call. |
| [Mint an SSH certificate for an agent](https://onecli.sh/docs/api-reference/agents/mint-an-ssh-certificate-for-an-agent.md) | `POST /agents/{agentId}/ssh-certificate` | Sign a short-lived OpenSSH user certificate to SSH into a hosted agent's sandbox, using an inline ed25519 key or a registered key. |

## Next steps

* [API overview](https://onecli.sh/docs/api-reference.md): base URLs, authentication, and pagination
* [Errors](https://onecli.sh/docs/api-reference/errors.md): status codes and the error format
* [Editions](https://onecli.sh/docs/api-reference/editions.md): which endpoints each edition serves


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.