@devries-cameron20 / composio-1 / commits / d2aea23f1
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: document agent account claim and route credential-less agents to agent signup (DEVREL-134) (#5373)

Part of [DEVREL-134](https://linear.app/composio/issue/DEVREL-134/make-agent-signup-discoverable-across-composio-website-docs-and). ## Problem Most of the agent-signup docs work has already shipped (#4434). The quickstart, `cli.mdx`, the agent-setup index, the authentication reference, and the docs `llms.txt` all link to [Authenticate an unattended agent](https://docs.composio.dev/docs/agent-setup/unattended-authentication). Two gaps were left: - The guide never mentioned handing the agent account to a person, even though the CLI ships `composio agent claim <email>`. - The bundled Composio skill (`skills/composio/SKILL.md`) never mentions agent signup. An agent that has only the skill, no key, and no human available has no documented next step. ## What changed - **`docs/content/docs/agent-setup/unattended-authentication.mdx`**: new "Hand the account to a human" section covering `composio agent claim <email>`. - **`skills/composio/SKILL.md`**: new stable rule 4. Reuse an existing credential first (`COMPOSIO_API_KEY`, a saved CLI login, or a saved agent identity). Use `composio login --agent` only when the task needs Composio, no credential exists, and no human is available. Mentioning Composio alone is not a reason to sign up, and an agent account does not authorize anyone's apps. Rules 4–11 become 5–12. Nothing references the rules by number. ## Evidence This is a docs and skill change, so there's no before/after output to show. I checked each claim in the new section against the CLI source: | Claim | Source | |---|---| | `composio agent claim <email>` invites the email as an admin of the agent org | `ts/packages/cli/src/commands/agent/claim/agent.claim.cmd.ts` (description: "Invite a human admin to claim this agent org.") | | Uses the saved agent key and fails when the CLI is signed in as a human | `resolveStoredAgentKey` in `ts/packages/cli/src/services/agents.ts` returns `humanLoginError()` when the current key isn't the stored agent's | | `composio agent whoami` reports `claimed_by`, `null` until set | `safeAgentSummary` (`claimed_by: identity.claimed_by ?? null`) and `formatAgentWhoamiJson` | Not run: the docs build and the static tests. Dependencies weren't installed because this ran on a shared machine. CI covers both. ## Details Out of scope here; the rest of DEVREL-134 stays on the ticket: - composio.dev homepage, For You, and footer links belong to the marketing site. - The fresh-agent discovery audit stays manual and is tracked on the ticket. - Toolkit page and package README links are on hold. ## ELI5 Agents can already create their own Composio account from the command line. This PR tells them how to hand that account to a person later. It also tells the Composio skill to use a key the agent already has, and to create an account only when there's no key and no human to log in. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Brendan O'Leary committed Nov 13, 2026 at 10:25 UTC d2aea23f11401813bc0aa3b381a2edb9ae1213f1
2 files changed +19 -8
docs/content/docs/agent-setup/unattended-authentication.mdx
+10
@@ -97,6 +97,16 @@ Then run the integration's own script or API route with the same project key and
97
98 For an authorized write action, verify the resulting object or state through a follow-up read or the provider's UI. Record the tool slug, sanitized result, and returned log ID if present. If only the Hacker News check succeeds, report that check separately from the requested integration action. If app authorization is unavailable, report the remaining connection step and leave the action unverified.
99
100 +## Hand the account to a human
101 +
102 +To let a person manage the agent's organization later, invite them as an admin from the machine that holds the agent identity:
103 +
104 +```bash
105 +composio agent claim person@example.com
106 +```
107 +
108 +The command uses the saved agent key and fails if the CLI is signed in as a human user. `composio agent whoami` reports the claiming admin in `claimed_by`, or `null` until the claim completes. Claiming is optional; the agent account works without it.
109 +
110 ## Log in with a human
111
112 When a human is available but your terminal cannot open a browser, print a login URL:
skills/composio/SKILL.md
+9 -8
@@ -54,14 +54,15 @@ Do not turn an explanation, documentation lookup, or narrow bug fix into onboard
54 1. Establish the product before choosing credentials, URLs, SDKs, or commands.
55 2. Treat dashboard onboarding as a context, not the skill's identity. When the developer arrives with an existing `COMPOSIO_API_KEY` from Getting Started, use it and never create, rotate, replace, print, or request it in chat. Do not run `composio dev init` in that path.
56 3. For a general first-time Platform setup with no dashboard credential handoff, follow the current setup path in the Platform guide.
57 -4. Never invent toolkit or tool slugs. Discover them at runtime or with the CLI.
58 -5. Do not build a provider OAuth flow. Composio returns a Connect Link when authentication is needed.
59 -6. Use sessions for new Platform integrations. Preserve the application's existing user identity and agent architecture.
60 -7. Keep credentials out of source control, URLs, logs, chat, and command output.
61 -8. Get the log or request ID before diagnosing a failed tool call.
62 -9. Prefer the smallest configuration that completes the current job. Keep toolkit filters, tag policies, approvals, Firewall hooks, Custom MCP toolkits, sandbox controls, custom auth, provider-specific hardening, and other advanced options out of the first path unless the request or existing code requires them. When the request does ask for one, such as "ask before sending" or "block prompt injection", use the documented feature instead of building a substitute in prompts or application code.
63 -10. Do not invent repository facts. Never claim that a file, framework, environment loader, identity field, agent path, or dependency exists until it was provided or inspected. If codebase context is unavailable, state the unknown and ask for access or one necessary detail.
64 -11. In SDK or API examples, use exact identifiers and call shapes from a current public page or schema. Copy the documented shape for the requested language instead of translating names between TypeScript and Python; if a required detail is not documented, explain the behavior without inventing code.
57 +4. Reuse an existing Composio credential first: a `COMPOSIO_API_KEY`, a saved CLI login, or a saved agent identity. Only when the task needs Composio, no credential exists, and no human is available to log in, follow [Authenticate an unattended agent](https://docs.composio.dev/docs/agent-setup/unattended-authentication) and run `composio login --agent`. A mention of Composio is not a reason to create an account, and an agent account does not authorize anyone's apps.
58 +5. Never invent toolkit or tool slugs. Discover them at runtime or with the CLI.
59 +6. Do not build a provider OAuth flow. Composio returns a Connect Link when authentication is needed.
60 +7. Use sessions for new Platform integrations. Preserve the application's existing user identity and agent architecture.
61 +8. Keep credentials out of source control, URLs, logs, chat, and command output.
62 +9. Get the log or request ID before diagnosing a failed tool call.
63 +10. Prefer the smallest configuration that completes the current job. Keep toolkit filters, tag policies, approvals, Firewall hooks, Custom MCP toolkits, sandbox controls, custom auth, provider-specific hardening, and other advanced options out of the first path unless the request or existing code requires them. When the request does ask for one, such as "ask before sending" or "block prompt injection", use the documented feature instead of building a substitute in prompts or application code.
64 +11. Do not invent repository facts. Never claim that a file, framework, environment loader, identity field, agent path, or dependency exists until it was provided or inspected. If codebase context is unavailable, state the unknown and ask for access or one necessary detail.
65 +12. In SDK or API examples, use exact identifiers and call shapes from a current public page or schema. Copy the documented shape for the requested language instead of translating names between TypeScript and Python; if a required detail is not documented, explain the behavior without inventing code.
66
67 ## Canonical information
68