Skip to content

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

refactor(python): merge examples into one file, fix mypy shadowing

Dhawal Upadhyayd1abe5df5641
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index b7227e6b0..2c40d7194 100644
--- a/python/composio/core/models/tool_router_session.py
+++ b/python/composio/core/models/tool_router_session.py
@@ -305,7 +305,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
# Build local result entries matching backend format
local_entries = []
for idx, result in local_results:
- entry: t.Dict[str, t.Any] = {
+ local_entry: t.Dict[str, t.Any] = {
"response": {
"successful": result["successful"],
"data": result["data"],
@@ -313,9 +313,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
"tool_slug": parsed[idx]["tool_slug"],
}
if result.get("error"):
- entry["response"]["error"] = result["error"]
- entry["error"] = result["error"]
- local_entries.append(entry)
+ local_entry["response"]["error"] = result["error"]
+ local_entry["error"] = result["error"]
+ local_entries.append(local_entry)
# Merge: remotes first, locals appended (matches TS behavior —
# remote results may be stored in workbench with index references)
diff --git a/python/examples/custom_tools_agent_test.py b/python/examples/custom_tools_agent_test.py
index f979f4d00..dbef5d88b 100644
--- a/python/examples/custom_tools_agent_test.py
+++ b/python/examples/custom_tools_agent_test.py
@@ -1,7 +1,9 @@
"""
-Custom Tools Agent Test — decorator API with OpenAI Agents SDK.
+Custom Tools — local tools + proxy execute with OpenAI Agents SDK.
-Tests all custom tool patterns end-to-end through a real LLM agent loop.
+Shows how to create custom tools that run in-process alongside
+remote Composio tools. Includes all three patterns: standalone,
+extension (Gmail proxy), and custom toolkit.
Usage:
COMPOSIO_API_KEY=... OPENAI_API_KEY=... python examples/custom_tools_agent_test.py
@@ -21,7 +23,7 @@ from composio_openai_agents import OpenAIAgentsProvider
composio = Composio(provider=OpenAIAgentsProvider())
-# ── 1. Standalone tool ──────────────────────────────────────────
+# ── 1. Standalone tool — slug/name/description inferred from function ──
class UserLookupInput(BaseModel):
@@ -43,7 +45,40 @@ def get_user(input: UserLookupInput, ctx):
return user
-# ── 2. Extension tool (Gmail proxy) ─────────────────────────────
+# slug = GET_USER (from function name)
+# name = Get User (humanized)
+# description = "Look up an internal user by ID..." (from docstring)
+
+
+# ── 2. Standalone tool with overrides ──────────────────────────────────
+
+
+class GreetInput(BaseModel):
+ name: str = Field(description="Name to greet")
+ style: str = Field(default="friendly", description="Greeting style")
+
+
+ slug="GREET_V2",
+ name="Greeting Generator",
+ description="Generate a personalized greeting message in different styles.",
+)
+def greet(input: GreetInput, ctx):
+ """This docstring is ignored because description= is set above."""
+ greetings = {
+ "friendly": f"Hey {input.name}! Great to see you!",
+ "formal": f"Dear {input.name}, I hope this message finds you well.",
+ "casual": f"Yo {input.name}, what's up?",
+ }
+ return {"message": greetings.get(input.style, f"Hello {input.name}!")}
+
+
+# slug = GREET_V2 (overridden, not GREET)
+# name = Greeting Generator (overridden, not Greet)
+# description = "Generate a personalized..." (overridden, not docstring)
+
+
+# ── 3. Extension tool — inherits Gmail auth via ctx.proxy_execute() ────
class DraftInput(BaseModel):
@@ -72,12 +107,7 @@ def create_draft(input: DraftInput, ctx):
return {"draft_id": data["id"], "to": input.to, "subject": input.subject}
-# ── 3. Custom toolkit ───────────────────────────────────────────
-
-
-class SetRoleInput(BaseModel):
- user_id: str = Field(description="User ID")
- role: str = Field(description="New role (admin, developer, viewer)")
+# ── 4. Custom toolkit — groups related tools under one namespace ───────
role_manager = composio.experimental.Toolkit(
@@ -87,13 +117,24 @@ role_manager = composio.experimental.Toolkit(
)
+class SetRoleInput(BaseModel):
+ user_id: str = Field(description="User ID")
+ role: str = Field(description="New role (admin, developer, viewer)")
+
+
@role_manager.tool()
def set_role(input: SetRoleInput, ctx):
"""Set a user's role. Returns confirmation."""
return {"user_id": input.user_id, "role": input.role, "updated": True}
-# ── Agent test runner ───────────────────────────────────────────
+@role_manager.tool(name="List All Roles")
+def list_roles(input: UserLookupInput, ctx):
+ """List available roles for a user."""
+ return {"roles": ["admin", "developer", "viewer"], "current": "admin"}
+
+
+# ── Agent ──────────────────────────────────────────────────────────────
async def run_test(prompt, test_name):
@@ -106,7 +147,7 @@ async def run_test(prompt, test_name):
toolkits=["gmail", "weathermap"],
manage_connections=True,
experimental={
- "custom_tools": [get_user, create_draft],
+ "custom_tools": [get_user, greet, create_draft],
"custom_toolkits": [role_manager],
},
)
@@ -133,48 +174,26 @@ async def run_test(prompt, test_name):
async def main():
- results = []
- results.append(
- ("Standalone (GET_USER)", await run_test("Look up user-2", "Standalone"))
- )
- results.append(
- (
- "Toolkit (SET_ROLE)",
- await run_test("Set user-1 role to developer", "Toolkit"),
- )
- )
- results.append(
- (
- "Mixed local",
- await run_test(
- "Look up user-1 and set their role to viewer", "Mixed local"
- ),
- )
- )
- results.append(
- (
- "Remote (weathermap)",
- await run_test("What is the weather in Tokyo?", "Remote"),
- )
- )
- results.append(
+ tests = [
+ ("Look up user-2", "Standalone (inferred slug/name)"),
+ ("Generate a formal greeting for Alice", "Standalone (overridden slug/name)"),
+ ("Set user-1 role to developer", "Toolkit tool"),
+ ("Look up user-1 and set their role to viewer", "Mixed local tools"),
+ ("What is the weather in Tokyo?", "Remote (weathermap)"),
(
- "Gmail proxy",
- await run_test(
- 'Create a Gmail draft to [email protected] with subject "Test" and body "Hello!"',
- "Gmail proxy",
- ),
- )
- )
- results.append(
+ 'Draft an email to [email protected] with subject "Test" and body "Hello!"',
+ "Gmail proxy (extends_toolkit)",
+ ),
(
- "Mixed all",
- await run_test(
- "Look up user-1, draft them an email saying hi, include weather in SF",
- "Mixed all",
- ),
- )
- )
+ "Look up user-1, draft them an email saying hi, include weather in SF",
+ "Mixed all paths",
+ ),
+ ]
+
+ results = []
+ for prompt, name in tests:
+ ok = await run_test(prompt, name)
+ results.append((name, ok))
print(f"\n{'=' * 60}")
print("RESULTS")
diff --git a/python/examples/custom_tools_v2.py b/python/examples/custom_tools_v2.py
deleted file mode 100644
index ea348ba83..000000000
--- a/python/examples/custom_tools_v2.py
+++ /dev/null
@@ -1,103 +0,0 @@
-"""
-Custom Tools v2 — decorator API for tool router sessions.
-
-Usage:
- COMPOSIO_API_KEY=... python examples/custom_tools_v2.py
-"""
-
-from pydantic import BaseModel, Field
-
-from composio import Composio
-
-
-composio = Composio()
-
-# ── 1. Standalone tool (no auth) ────────────────────────────────
-
-
-class UserLookupInput(BaseModel):
- user_id: str = Field(description="User ID (e.g. user-1)")
-
-
-USERS = {
- "user-1": {"name": "Alice Johnson", "email": "[email protected]", "role": "admin"},
- "user-2": {"name": "Bob Smith", "email": "[email protected]", "role": "developer"},
-}
-
-
-def get_user(input: UserLookupInput, ctx):
- """Look up an internal user by ID."""
- user = USERS.get(input.user_id)
- if not user:
- raise ValueError(f'User "{input.user_id}" not found')
- return user
-
-
-# ── 2. Custom toolkit with grouped tools ────────────────────────
-
-
-class SetRoleInput(BaseModel):
- user_id: str = Field(description="User ID")
- role: str = Field(description="New role (admin, developer, viewer)")
-
-
-role_manager = composio.experimental.Toolkit(
- slug="ROLE_MANAGER",
- name="Role Manager",
- description="Manage user roles",
-)
-
-
-@role_manager.tool()
-def set_role(input: SetRoleInput, ctx):
- """Set a user's role."""
- return {
- "user_id": input.user_id,
- "role": input.role,
- "updated": True,
- }
-
-
-# ── Session ─────────────────────────────────────────────────────
-
-
-def main():
- print("Creating session with custom tools...")
- session = composio.create(
- user_id="default",
- experimental={
- "custom_tools": [get_user],
- "custom_toolkits": [role_manager],
- },
- )
- print(f"Session ID: {session.session_id}")
-
- print("\n── Registered custom tools ──")
- for tool in session.custom_tools():
- print(f" {tool.slug} ({tool.toolkit or 'standalone'})")
-
- print("\n── Test: GET_USER ──")
- result = session.execute("GET_USER", arguments={"user_id": "user-1"})
- print(f" {result}")
- assert result["data"]["name"] == "Alice Johnson"
- print(" PASS")
-
- print("\n── Test: SET_ROLE ──")
- result = session.execute(
- "SET_ROLE", arguments={"user_id": "user-1", "role": "viewer"}
- )
- print(f" {result}")
- assert result["data"]["updated"] is True
- print(" PASS")
-
- print("\n── Test: Validation error ──")
- result = session.execute("GET_USER", arguments={})
- assert result["error"] is not None
- print(" PASS")
-
- print("\nAll tests passed!")
-
-
-if __name__ == "__main__":
- main()