> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic

> Build an agent with Claude and enable it to use 1000+ tools with Composio.

The Anthropic provider formats Composio tools for Claude and executes the tool calls Claude returns. It works two ways:

* The [Claude Messages API](https://docs.anthropic.com/en/api/messages), where you run the tool-call loop yourself.
* The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), where the SDK runs the loop and Composio tools are exposed as an in-process MCP server.

Pick the tab that matches your integration.

> [tab] Messages API
>
> The `AnthropicProvider` transforms Composio tools into the format the Claude Messages API expects, then executes the tool calls Claude requests and shapes the results back into Messages API content blocks.
>
> **1. Install**
>
> **Install**
>
> > [tab] Python
> >
> > ```bash uv theme={null}
> > uv add composio composio_anthropic anthropic
> > ```
> >
> > ```bash pip theme={null}
> > pip install composio composio_anthropic anthropic
> > ```
>
> > [tab] TypeScript
> >
> > ```bash npm theme={null}
> > npm install @composio/core @composio/anthropic @anthropic-ai/sdk
> > ```
> >
> > ```bash pnpm theme={null}
> > pnpm add @composio/core @composio/anthropic @anthropic-ai/sdk
> > ```
> >
> > ```bash yarn theme={null}
> > yarn add @composio/core @composio/anthropic @anthropic-ai/sdk
> > ```
> >
> > ```bash bun theme={null}
> > bun add @composio/core @composio/anthropic @anthropic-ai/sdk
> > ```
>
> **2. Configure API Keys**
>
> **Configure API Keys**
>
> > [!NOTE]
> >
> > Set `COMPOSIO_API_KEY` with your API key from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs\&utm_medium=content\&utm_campaign=docs-providers-anthropic) and `ANTHROPIC_API_KEY` with your [Anthropic API key](https://console.anthropic.com/settings/keys).
>
> ```txt .env theme={null}
> COMPOSIO_API_KEY=xxxxxxxxx
> ANTHROPIC_API_KEY=xxxxxxxxx
> ```
>
> **3. Create session and run**
>
> **Create session and run**
>
> > [!NOTE]
> >
> > Passing a session to `handle_tool_calls` / `handleToolCalls` requires `composio` newer than 0.19.0 (Python) or `@composio/core` ≥ 0.17.0 with `@composio/anthropic` ≥ 0.11.0 (TypeScript). On earlier versions, execute session tools with [`session.execute()`](https://composio-preview.mintlify.site/docs/how-composio-works#executing-session-tools).
>
> > [tab] Python
> >
> > ```python theme={null}
> > import json
> >
> > import anthropic
> > from composio import Composio
> > from composio_anthropic import AnthropicProvider
> >
> > provider = AnthropicProvider()
> > composio = Composio(provider=provider)
> > client = anthropic.Anthropic()
> >
> > # Create a session for your user
> > session = composio.create(user_id="user_123")
> > tools = session.tools()
> >
> > messages = [
> >     {"role": "user", "content": "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'"}
> > ]
> >
> > response = client.messages.create(
> >     model="claude-opus-5-5",
> >     max_tokens=4096,
> >     tools=tools,
> >     messages=messages,
> > )
> >
> > # Agentic loop: keep executing tool calls until the model responds with text
> > while response.stop_reason == "tool_use":
> >     tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
> >     results = provider.handle_tool_calls(response=response, session=session)
> >     messages.append({"role": "assistant", "content": response.content})
> >     messages.append({
> >         "role": "user",
> >         "content": [
> >             {"type": "tool_result", "tool_use_id": tool_use_blocks[i].id, "content": json.dumps(result)}
> >             for i, result in enumerate(results)
> >         ],
> >     })
> >     response = client.messages.create(
> >         model="claude-opus-5-5",
> >         max_tokens=4096,
> >         tools=tools,
> >         messages=messages,
> >     )
> >
> > # Print final response
> > for block in response.content:
> >     if block.type == "text":
> >         print(block.text)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import Anthropic from '@anthropic-ai/sdk';
> > import { Composio } from '@composio/core';
> > import { AnthropicProvider } from '@composio/anthropic';
> >
> > const composio = new Composio({
> >     provider: new AnthropicProvider(),
> > });
> > const client = new Anthropic();
> >
> > // Create a session for your user
> > const session = await composio.create("user_123");
> > const tools = await session.tools();
> >
> > const messages: Anthropic.MessageParam[] = [
> >     {
> >         role: "user",
> >         content: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'"
> >     },
> > ];
> >
> > let response = await client.messages.create({
> >     model: "claude-opus-5-5",
> >     max_tokens: 4096,
> >     tools: tools,
> >     messages: messages,
> > });
> >
> > // Agentic loop: keep executing tool calls until the model responds with text
> > while (response.stop_reason === "tool_use") {
> >     const toolResults = await composio.provider.handleToolCalls(session, response);
> >     messages.push({ role: "assistant", content: response.content });
> >     messages.push(...toolResults);
> >     response = await client.messages.create({
> >         model: "claude-opus-5-5",
> >         max_tokens: 4096,
> >         tools: tools,
> >         messages: messages,
> >     });
> > }
> >
> > // Print final response
> > for (const block of response.content) {
> >     if (block.type === "text") {
> >         console.log(block.text);
> >     }
> > }
> > ```
>
> > [!NOTE]
> >
> > Pass the session to `handleToolCalls` / `handle_tool_calls` when the model received tools from `session.tools()`. The helper preserves Anthropic input normalization and restored schema aliases before executing every call through that session. For tools fetched via [`tools.get`](https://composio-preview.mintlify.site/docs/tools-direct/executing-tools), pass the user ID instead.

> [tab] Claude Agent SDK
>
> The `ClaudeAgentSDKProvider` exposes your Composio tools to the Claude Agent SDK as an in-process MCP server. You build the server with `create_sdk_mcp_server` (Python) or `createSdkMcpServer` (TypeScript), register it on the agent, and the SDK runs the tool-call loop for you.
>
> **1. Install**
>
> **Install**
>
> > [tab] Python
> >
> > ```bash uv theme={null}
> > uv add composio composio_claude_agent_sdk claude-agent-sdk
> > ```
> >
> > ```bash pip theme={null}
> > pip install composio composio_claude_agent_sdk claude-agent-sdk
> > ```
>
> > [tab] TypeScript
> >
> > ```bash npm theme={null}
> > npm install @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > ```bash pnpm theme={null}
> > pnpm add @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > ```bash yarn theme={null}
> > yarn add @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > ```bash bun theme={null}
> > bun add @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > > [!WARNING]
> > >
> > > The TypeScript provider requires Zod `4.1.13` or newer. Upgrade Zod before upgrading `@composio/claude-agent-sdk`; older Zod v4 versions lack the shared metadata registry the provider needs to preserve schema annotations.
>
> **2. Configure API Keys**
>
> **Configure API Keys**
>
> > [!NOTE]
> >
> > Set `COMPOSIO_API_KEY` with your API key from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs\&utm_medium=content\&utm_campaign=docs-providers-anthropic) and `ANTHROPIC_API_KEY` with your [Anthropic API key](https://console.anthropic.com/settings/keys).
>
> ```txt .env theme={null}
> COMPOSIO_API_KEY=xxxxxxxxx
> ANTHROPIC_API_KEY=xxxxxxxxx
> ```
>
> **3. Create session and run**
>
> **Create session and run**
>
> > [tab] Python
> >
> > ```python theme={null}
> > import asyncio
> > from composio import Composio
> > from composio_claude_agent_sdk import ClaudeAgentSDKProvider
> > from claude_agent_sdk import AssistantMessage, ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server
> >
> > composio = Composio(provider=ClaudeAgentSDKProvider())
> >
> > # Create a session for your user
> > session = composio.create(user_id="user_123")
> > tools = session.tools()
> > tool_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
> >
> > async def main():
> >     options = ClaudeAgentOptions(
> >         system_prompt="You are a helpful assistant",
> >         permission_mode="bypassPermissions",
> >         mcp_servers={"composio": tool_server},
> >     )
> >
> >     async with ClaudeSDKClient(options=options) as client:
> >         await client.query("Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'")
> >         async for msg in client.receive_response():
> >             if isinstance(msg, AssistantMessage):
> >                 print("Claude:", msg.content)
> >
> > asyncio.run(main())
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
> > import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
> >
> > const composio = new Composio({
> >     provider: new ClaudeAgentSDKProvider(),
> > });
> >
> > // Create a session for your user
> > const session = await composio.create("user_123");
> > const tools = await session.tools();
> > const toolServer = createSdkMcpServer({
> >     name: "composio",
> >     version: "1.0.0",
> >     tools: tools,
> > });
> >
> > for await (const content of query({
> >     prompt: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
> >     options: {
> >         systemPrompt: "You are a helpful assistant",
> >         mcpServers: { composio: toolServer },
> >         permissionMode: "bypassPermissions",
> >     },
> > })) {
> >     if (content.type === "assistant") {
> >         console.log("Claude:", content.message);
> >     }
> > }
> > ```
> >
> > The provider registers each tool's complete object schema. Object arguments that declare no properties reach execution with arbitrary nested keys unchanged, while root-level constraints such as `additionalProperties` and `patternProperties` remain enforced. Invalid arguments return an error result, and the tool does not run.

## Provider specifics

A few things are specific to the Anthropic provider:

* **Tool caching.** Pass `cacheTools: true` to the constructor (`new AnthropicProvider({ cacheTools: true })`) to attach Anthropic's ephemeral `cache_control` to the last tool definition, which caches the whole tool list. This lets Claude reuse cached tool schemas across requests and can cut prompt cost when you send the same large tool set on every turn. Anthropic allows at most 4 `cache_control` breakpoints per request, so tool-result blocks are not marked, and lists merged from several `wrapTools` calls each keep a breakpoint on their last tool.
* **`handleToolCalls` returns Messages API content, not raw strings.** TypeScript returns a ready-to-append `user` message of `tool_result` blocks. Python returns raw results in model-call order, which the sample wraps into `tool_result` blocks.
* **String-encoded tool inputs are handled for you.** Claude occasionally emits a tool's `input` as a JSON string instead of an object. The provider normalizes it before both direct and session execution.
* **`cacheTools` only.** The constructor takes no other options. There is no agentic execution in this provider; you run the loop (Messages API) or hand the loop to the Claude Agent SDK (Agent SDK tab).
* **Python tool caching.** Pass `cache_tools=True` to the constructor (`AnthropicProvider(cache_tools=True)`) to attach Anthropic's ephemeral `cache_control` to the tool definitions, as `cacheTools` does in TypeScript. `wrap_tools` marks only the last tool, which caches the whole tool list within Anthropic's limit of 4 breakpoints per request. Tool results are not marked.

## Next

> [card] [What is a session?](https://composio-preview.mintlify.site/docs/how-composio-works.md)
>
> How sessions scope users, tools, and auth, and how to reuse them across requests.
