Create Agent - POST /v1/agents

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" }
  }'

{
  "id": "ag_01J1234567890ABCDEF",
  "object": "agent",
  "name": "SupportBot",
  "model": "gpt-4o",
  "instructions": "You are a helpful support assistant.",
  "tools": [],
  "metadata": { "team": "support" }
}

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" }
  }'

{
  "id": "ag_01J1234567890ABCDEF",
  "object": "agent",
  "name": "SupportBot",
  "model": "gpt-4o",
  "instructions": "You are a helpful support assistant.",
  "tools": [],
  "metadata": { "team": "support" }
}

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

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

string

required

Human-readable name for the agent.

string

required

Model identifier used by the agent (for example, gpt-4o).

string

System prompt or instructions that guide the agent’s behavior.

array

List of tool definitions available to the agent.

object

Arbitrary key-value pairs for your own bookkeeping.

Response

string

Unique identifier for the agent.

string

Always agent.

string

The agent’s name.

string

The model identifier.

string

System instructions, if provided.

array

Tools registered for the agent.

object

Metadata map attached to the agent.

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" }
  }'

{
  "id": "ag_01J1234567890ABCDEF",
  "object": "agent",
  "name": "SupportBot",
  "model": "gpt-4o",
  "instructions": "You are a helpful support assistant.",
  "tools": [],
  "metadata": { "team": "support" }
}

PIN API

ROUTER API

AGENT API

Create Agent - POST /v1/agents

Endpoint

Authentication

Request Body

Response

​Endpoint

​Authentication

​Request Body

​Response

Endpoint

Authentication

Request Body

Response