# Signing Up as an Agent (/docs/signing-up-as-an-agent)

Agents can sign up for Composio directly through [`agents.composio.dev`](https://agents.composio.dev) without a human creating an account first. The flow creates an agent identity, returns Composio credentials, and gives the agent a ready-to-run CLI install/login command.

The base URL for all endpoints on this page is:

```text
https://agents.composio.dev
```

# Flow

1. **Check for an existing identity.** Before signing up, look for `~/.composio/anonymous_user_data.json`. If it exists, read the saved `agent_key` and call `GET /api/whoami` with `Authorization: Bearer <agent_key>`. If it returns `200` with `status: "READY"`, reuse the saved credentials.
2. **Sign up.** Call `POST /api/signup`. By default, the endpoint waits until the account is ready and returns a `201` response containing the `agent_key` plus Composio credentials (`member_id`, `org_id`, `project_id`, `api_key`, and `user_api_key`). Save the full response to `~/.composio/anonymous_user_data.json` immediately so future runs do not create a new identity.
3. **Install and log in to the CLI.** Call `GET /api/cli` with the `agent_key`. It returns paste-ready install and login commands.
4. **Optionally claim the org.** Call `POST /api/claim` with a human email only when you want to hand the organization over to a human admin.

# Sign up

`POST /api/signup` creates an agent email inbox, starts the Composio signup flow, and long-polls for up to 120 seconds. Most calls complete in about 5–10 seconds.

```bash
mkdir -p ~/.composio

curl -sS -X POST 'https://agents.composio.dev/api/signup' \
  -H 'content-type: application/json' \
  -d '{}' \
  -o ~/.composio/anonymous_user_data.json

cat ~/.composio/anonymous_user_data.json
```

Successful response:

```json
{
  "status": "ready",
  "request_id": "req_xxx",
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "agent_key": "composio_agent_key_xxx",
  "composio": {
    "member_id": "uuid",
    "org_id": "org_xxx",
    "project_id": "proj_xxx",
    "api_key": "ak_xxx",
    "user_api_key": "uak_xxx"
  }
}
```

If the 120-second wait expires, the endpoint returns `202` with `status: "pending"`. Poll `GET /api/whoami` until the status is `READY`.

```json
{
  "status": "pending",
  "request_id": "req_xxx",
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "agent_key": "composio_agent_key_xxx",
  "poll": "/api/whoami"
}
```

To skip waiting and poll yourself, pass `?wait=0`:

```bash
curl -sS -X POST 'https://agents.composio.dev/api/signup?wait=0' \
  -H 'content-type: application/json' \
  -d '{}'
```

# Verify a saved identity

Use `GET /api/whoami` to verify a saved `agent_key` and fetch the current Composio credentials. The `agent_key` authenticates only against the agent signup surface; it is not your Composio API key.

```bash
AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS 'https://agents.composio.dev/api/whoami' \
  -H "Authorization: Bearer ${AGENT_KEY}"
```

Response:

```json
{
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "status": "READY",
  "claimed_by": null,
  "claimed_at": null,
  "composio": {
    "member_id": "uuid",
    "org_id": "org_xxx",
    "project_id": "proj_xxx",
    "api_key": "ak_xxx",
    "user_api_key": "uak_xxx"
  }
}
```

# Install the CLI

`GET /api/cli` returns install and login commands with the agent's `user_api_key` and `org_id` already filled in.

```bash
AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS 'https://agents.composio.dev/api/cli' \
  -H "Authorization: Bearer ${AGENT_KEY}"
```

Example response:

```text
Install Composio CLI using this command:
curl -fsSL https://composio.dev/install | bash

Then log in using this command:
composio login --user-api-key "uak_..." --org "ok_..."
```

Run the returned commands to install and authenticate the CLI.

# Claim the organization

Claiming is optional. Use it only when the agent wants to invite a human admin to take over the Composio organization. The endpoint issues a single-use admin invite that expires after 24 hours.

```bash
AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS -X POST 'https://agents.composio.dev/api/claim' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -H 'content-type: application/json' \
  -d '{"email":"human@example.com"}'
```

Response:

```json
{
  "status": "invited",
  "email": "human@example.com",
  "org_id": "org_xxx",
  "invite_code": "inv_xxx"
}
```

# Read the agent inbox

Each agent gets an email address at `<slug>@agent.composio.ai`. Use `GET /api/mail` to list messages for the agent inbox.

```bash
AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS 'https://agents.composio.dev/api/mail?limit=50' \
  -H "Authorization: Bearer ${AGENT_KEY}"
```

Response:

```json
{
  "count": 1,
  "messages": [
    {
      "id": "msg_xxx",
      "thread_id": "thr_xxx",
      "from": "no-reply@composio.dev",
      "to": "amber-cedar-otter@agent.composio.ai",
      "subject": "Sign in to Composio",
      "preview": "Click the link below to sign in...",
      "received_at": "2026-04-13T22:00:00.000Z"
    }
  ]
}
```

# Agent keys

Agent keys are prefixed with `composio_agent_key_` and are only valid for these endpoints:

* `GET /api/whoami`
* `GET /api/mail`
* `GET /api/cli`
* `POST /api/claim`

Use the real Composio API key from the `composio.api_key` field when calling Composio APIs and SDKs.

---

📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/docs/glossary) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)

---

# Composio SDK — Instructions for AI Code Generators

**Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents.
**Scope:** All AI-generated code using Composio must follow these guardrails.

---

## 1. Correct Composio Integration

Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).

### Native Tools

```python
# ✅ CORRECT — Python (defaults to OpenAI)
from composio import Composio

composio = Composio()
session = composio.create(user_id="user_123")
tools = session.tools()
# Pass tools to your agent/LLM framework
```

```typescript
// ✅ CORRECT — TypeScript (defaults to OpenAI)
import { Composio } from "@composio/core";

const composio = new Composio();
const session = await composio.create("user_123");
const tools = await session.tools();
// Pass tools to your agent/LLM framework
```

For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_<provider>` for Python, `@composio/<provider>` for TypeScript.

### MCP

Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed.

---

## 2. CRITICAL INSTRUCTIONS FOR AI MODELS

### 2.1 — ALWAYS DO THE FOLLOWING

1. **Use `composio.create(user_id)`** to create a session — this is the entry point for all Composio integrations.
2. **Use `session.tools()`** for native tool integration or **`session.mcp.url`** for MCP integration.
3. **Import** from the correct provider package (`composio_<provider>` for Python, `@composio/<provider>` for TypeScript).
4. **Pass `user_id` to `composio.create()`**, not to individual tool calls.

### 2.2 — NEVER DO THE FOLLOWING

1. **Do not** instruct users to manually create auth configs or connected accounts before running.
2. **Do not** import from `composio_openai` / `@composio/openai` when using OpenAI Agents SDK — use `composio_openai_agents` / `@composio/openai-agents` instead.

### 2.3 — DISCOURAGED (do not use unless user explicitly asks)

Do **not** generate `composio.tools.get()`, `composio.tools.execute()`, or `composio.provider.handle_tool_calls()` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface.


---

## Terminology Migration (old → current)

If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.**

| Old term (v1/v2) | Current term (v3) | In code |
|---|---|---|
| entity ID | user ID | `user_id` parameter |
| actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* |
| apps / appType | toolkits | e.g., `github` is a *toolkit* |
| integration / integration ID | auth config / auth config ID | `auth_config_id` parameter |
| connection | connected account | `connected_accounts` namespace |
| ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` |
| toolset | provider | e.g., `OpenAIProvider` |

If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.