@devries-cameron20 / composio-1 / commits / f4a3b4aef
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.

feat(anthropic): add prompt-caching support to the Python provider (#4722)

`AnthropicProvider` had no `cache_control` option at all, unlike the TypeScript `AnthropicProvider`'s `cacheTools` option — the docs describe tool caching as TS-specific, even though the Python `anthropic` SDK's own `ToolParam` already has a native `cache_control` field. Fixes #4720 ## Changes - Adds a `cache_tools` constructor option (default `False`) that attaches Anthropic's ephemeral `cache_control` to the tool definitions. `wrap_tools` marks only the last tool, because Anthropic allows at most 4 breakpoints per request (shared across the system prompt, tools, and messages) and a breakpoint caches everything up to and including it. `wrap_tool` on its own marks the tool it returns. The key is omitted entirely when disabled, not set to `None`. This matches the TS `cacheTools` behaviour after #4724. - The limit is per request, not per call: if you concatenate lists from several `wrap_tools` calls, each list's last tool keeps its breakpoint. The `wrap_tool` and `wrap_tools` docstrings say so. - Scoped to the tool definitions (`wrap_tool` and `wrap_tools`): `handle_tool_calls` returning raw `ToolExecutionResponse` objects rather than building `tool_result` blocks (where TS's caching also applies) is an existing, already-documented Python/TS asymmetry this change doesn't touch — there's no `tool_result` block construction anywhere in the Python provider to attach a cache breakpoint to. - New `providers/anthropic/tests/test_provider.py` — this provider had no behavioral test file before (only a type-inference test). Covers: default omits `cache_control`, enabling it attaches `{"type": "ephemeral"}`, only the last tool of a batch carries it via `wrap_tools`, and schema/name/ description are unaffected. - Wired the new test directory into `noxfile.py`'s `tst` session (installs and runs each provider's own `test_provider.py` as a separate pytest invocation, same pattern already used for `openai_agents`/`claude_agent_sdk`). ## Type of change - [ ] Bug fix - [x] New feature - [ ] Refactor/Chore - [ ] Documentation - [ ] Breaking change ## How Has This Been Tested? `uv run pytest providers/anthropic/tests/test_provider.py tests/test_type_inference_anthropic.py` — 11 passed (6 new in `providers/anthropic/tests`), no regressions. `ruff check`/`ruff format --check`: clean. `mypy --config-file config/mypy.ini providers/anthropic/`: same 2 pre-existing, unrelated errors as unmodified `next` (confirmed via `git stash`), none on the changed files. ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the third-party links policy — n/a - [x] I ran linters/tests locally and they passed - [ ] I updated documentation as needed — n/a, same reasoning as Part 1 - [x] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages — **not applicable**, same reasoning as Part 1 (Python-only change, changesets are TS-only in this repo) --------- Co-authored-by: jkomyno <alberto@composio.dev>

Avanish Garg committed Oct 12, 2026 at 16:26 UTC f4a3b4aef0f9ee9b865939edcb4c8a888d3602f8
5 files changed +129 -3
.github/workflows/py.test.yml
+2
@@ -96,6 +96,7 @@ jobs:
96 uv pip install -e providers/google
97 uv pip install -e providers/openai_agents
98 uv pip install -e providers/claude_agent_sdk
99 + uv pip install -e providers/anthropic
100 uv pip install hypothesis pytest pytest-mock
101
102 - name: Run Import Tests
@@ -147,6 +148,7 @@ jobs:
148 # with tests/, which pytest cannot collect in a single session.
149 python -m pytest providers/openai_agents/tests -v --tb=short
150 python -m pytest providers/claude_agent_sdk/tests -v --tb=short
151 + python -m pytest providers/anthropic/tests -v --tb=short
152
153 - name: Test Package Installation
154 run: |
docs/content/docs/providers/anthropic.mdx
+1
@@ -280,6 +280,7 @@ A few things are specific to the Anthropic provider:
280 - **`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.
281 - **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.
282 - **`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).
283 +- **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.
284
285 ## Next
286
python/noxfile.py
+2
@@ -113,6 +113,7 @@ def tst(session: Session):
113 session.install("./providers/google")
114 session.install("./providers/openai_agents")
115 session.install("./providers/claude_agent_sdk")
116 + session.install("./providers/anthropic")
117 if session.posargs:
118 session.run("pytest", *session.posargs, "-v", "--tb=short")
119 return
@@ -122,6 +123,7 @@ def tst(session: Session):
123 "tests/",
124 "providers/openai_agents/tests",
125 "providers/claude_agent_sdk/tests",
126 + "providers/anthropic/tests",
127 ):
128 session.run("pytest", test_path, "-v", "--tb=short")
129
python/providers/anthropic/composio_anthropic/provider.py
+45 -3
@@ -1,6 +1,7 @@
1 import typing as t
2
3 from anthropic.types.beta.beta_tool_use_block import BetaToolUseBlock
4 +from anthropic.types.cache_control_ephemeral_param import CacheControlEphemeralParam
5 from anthropic.types.message import Message as ToolsBetaMessage
6 from anthropic.types.tool_param import ToolParam
7 from anthropic.types.tool_use_block import ToolUseBlock
@@ -22,21 +23,62 @@ class AnthropicProvider(
23 Composio toolset for Anthropic Claude platform.
24 """
25
25 - def __init__(self, **kwargs: t.Any) -> None:
26 + def __init__(self, cache_tools: bool = False, **kwargs: t.Any) -> None:
27 + """
28 + :param cache_tools: Attach Anthropic's ephemeral cache_control to the
29 + tool definitions so Claude can reuse the cached tool schemas
30 + across requests. Anthropic allows at most 4 cache_control
31 + breakpoints per request, shared across the system prompt, tools,
32 + and messages, and a breakpoint caches everything up to and
33 + including it — so :meth:`wrap_tools` places a single breakpoint
34 + on the last tool, covering the whole tool list with one
35 + breakpoint. Mirrors the TypeScript
36 + ``AnthropicProvider({ cacheTools: true })`` option. Defaults to
37 + ``False``.
38 + """
39 super().__init__(**kwargs)
40 + self.cache_tools = cache_tools
41 self._aliases: dict[str, ToolSchemaAliases] = {}
42
43 def wrap_tool(self, tool: Tool) -> ToolParam:
44 + """
45 + Wrap a single tool.
46 +
47 + With ``cache_tools`` enabled the returned tool carries its own
48 + ``cache_control`` breakpoint. If you build a tool list yourself from
49 + several calls, keep the number of breakpoints within Anthropic's
50 + limit, or use :meth:`wrap_tools`, which marks only the last tool.
51 + """
52 aliases = alias_tool_input_schema(tool.input_parameters or {})
53 self._aliases[tool.slug] = aliases
32 - return ToolParam(
54 + wrapped = ToolParam(
55 input_schema=aliases.schema,
56 name=tool.slug,
57 description=tool.description,
58 )
59 + if self.cache_tools:
60 + wrapped["cache_control"] = CacheControlEphemeralParam(type="ephemeral")
61 + return wrapped
62
63 def wrap_tools(self, tools: t.Sequence[Tool]) -> list[ToolParam]:
39 - return [self.wrap_tool(tool) for tool in tools]
64 + """
65 + Wrap a list of tools.
66 +
67 + With ``cache_tools`` enabled only the last tool in the list carries a
68 + ``cache_control`` breakpoint. The limit of 4 applies to the whole
69 + request, not to one call, so if you concatenate the lists from several
70 + calls, each list's last tool keeps its breakpoint.
71 + """
72 + wrapped = [self.wrap_tool(tool) for tool in tools]
73 + # A cache_control breakpoint caches every block up to and including
74 + # it, so one breakpoint on the last tool covers the entire tool list.
75 + # Anthropic caps breakpoints at 4 per request (shared with the system
76 + # prompt and messages); a breakpoint on every tool would exceed that
77 + # limit as soon as a caller passes 5+ tools.
78 + if self.cache_tools:
79 + for tool_param in wrapped[:-1]:
80 + tool_param.pop("cache_control", None)
81 + return wrapped
82
83 @t.overload
84 def execute_tool_call(
python/providers/anthropic/tests/test_provider.py new
+79
@@ -0,0 +1,79 @@
1 +"""Tests for the Anthropic provider."""
2 +
3 +from unittest.mock import MagicMock
4 +
5 +from composio_anthropic.provider import AnthropicProvider
6 +
7 +
8 +def _tool(slug="SEARCH_TOOL", description="Search for information"):
9 + return MagicMock(
10 + slug=slug,
11 + description=description,
12 + input_parameters={
13 + "type": "object",
14 + "properties": {"query": {"type": "string"}},
15 + "required": ["query"],
16 + },
17 + )
18 +
19 +
20 +def test_wrap_tool_omits_cache_control_by_default():
21 + """No `cache_tools` option means no cache_control on the wrapped tool."""
22 + wrapped = AnthropicProvider().wrap_tool(_tool())
23 +
24 + assert "cache_control" not in wrapped
25 +
26 +
27 +def test_wrap_tool_attaches_ephemeral_cache_control_when_cache_tools_enabled():
28 + """`cache_tools=True` attaches Anthropic's ephemeral cache breakpoint to
29 + the tool `wrap_tool` returns.
30 + """
31 + wrapped = AnthropicProvider(cache_tools=True).wrap_tool(_tool())
32 +
33 + assert wrapped["cache_control"] == {"type": "ephemeral"}
34 +
35 +
36 +def test_wrap_tools_caches_only_the_last_tool():
37 + """`wrap_tools` places a single breakpoint on the last tool: a breakpoint
38 + caches everything up to and including it, so one is enough to cover the
39 + whole tool list. Anthropic caps requests at 4 breakpoints total (shared
40 + with the system prompt and messages); a breakpoint on every tool would
41 + blow past that limit once a caller passes 5+ tools.
42 + """
43 + tools = [_tool(slug="TOOL_A"), _tool(slug="TOOL_B"), _tool(slug="TOOL_C")]
44 +
45 + wrapped_tools = AnthropicProvider(cache_tools=True).wrap_tools(tools)
46 +
47 + assert all("cache_control" not in t for t in wrapped_tools[:-1])
48 + assert wrapped_tools[-1]["cache_control"] == {"type": "ephemeral"}
49 +
50 +
51 +def test_wrap_tools_single_tool_still_gets_cache_control():
52 + """A batch of exactly one tool is also "the last tool" and should still
53 + be cached.
54 + """
55 + wrapped_tools = AnthropicProvider(cache_tools=True).wrap_tools([_tool()])
56 +
57 + assert wrapped_tools[-1]["cache_control"] == {"type": "ephemeral"}
58 +
59 +
60 +def test_wrap_tools_omits_cache_control_by_default():
61 + """No `cache_tools` option means no cache_control anywhere in the batch,
62 + including the last tool.
63 + """
64 + tools = [_tool(slug="TOOL_A"), _tool(slug="TOOL_B")]
65 +
66 + wrapped_tools = AnthropicProvider().wrap_tools(tools)
67 +
68 + assert all("cache_control" not in t for t in wrapped_tools)
69 +
70 +
71 +def test_wrap_tool_still_preserves_schema_and_metadata_with_caching_enabled():
72 + """Enabling caching must not change the wrapped tool's schema/name/description."""
73 + tool = _tool()
74 +
75 + wrapped = AnthropicProvider(cache_tools=True).wrap_tool(tool)
76 +
77 + assert wrapped["name"] == tool.slug
78 + assert wrapped["description"] == tool.description
79 + assert wrapped["input_schema"] == tool.input_parameters