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

# Create Agent - POST /v1/agents

> Create a new agent by posting an OpenAI-compatible Agent object with name, model, instructions, tools, and metadata. Returns the created agent.

Create an agent on Aria Compute by sending its name, model, and optional fields like instructions, tools, and metadata. The shape mirrors the OpenAI beta Agent object, so existing SDK code works with minimal changes.

## Endpoint

```http theme={null}
POST /v1/agents
```

## Authentication

`Authorization: Bearer <api_key>` or `Authorization: ApiKey <key>`. Optional if `AGENT_CLOUD_API_KEY` is unset at server boot.

## Request Body

<ParamField body="name" type="string" required>
  Human-readable name for the agent.
</ParamField>

<ParamField body="model" type="string" required>
  Model identifier used by the agent (for example, `gpt-4o`).
</ParamField>

<ParamField body="instructions" type="string">
  System prompt or instructions that guide the agent's behavior.
</ParamField>

<ParamField body="tools" type="array">
  List of tool definitions available to the agent.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs for your own bookkeeping.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the agent.
</ResponseField>

<ResponseField name="object" type="string">
  Always `agent`.
</ResponseField>

<ResponseField name="name" type="string">
  The agent's name.
</ResponseField>

<ResponseField name="model" type="string">
  The model identifier.
</ResponseField>

<ResponseField name="instructions" type="string">
  System instructions, if provided.
</ResponseField>

<ResponseField name="tools" type="array">
  Tools registered for the agent.
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadata map attached to the agent.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://agent.example.com/v1/agents \
    -H "Authorization: Bearer <api_key>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "SupportBot",
      "model": "gpt-4o",
      "instructions": "You are a helpful support assistant.",
      "metadata": { "team": "support" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "ag_01J1234567890ABCDEF",
    "object": "agent",
    "name": "SupportBot",
    "model": "gpt-4o",
    "instructions": "You are a helpful support assistant.",
    "tools": [],
    "metadata": { "team": "support" }
  }
  ```
</ResponseExample>


## Related topics

- [List Agents - GET /v1/agents](/api-reference/agent/agents/list.md)
- [Create Aria Agent Cloud Session for an Agent](/api-reference/agent/sessions/create.md)
- [POST /v1/apikeys — Create PIN API Key](/api-reference/pin/apikeys/create.md)
- [Create Agent Event](/api-reference/agent/events/create.md)
- [Update an Agent](/api-reference/pin/agents/update.md)