Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
import json
import os
import random
import time
import urllib.error
import urllib.parse
import urllib.request
import uuid
from typing import Any, Dict, Literal, Optional
# Config is injected by the SDK via an `_INTERNAL` dict in a prologue prepended
# at runtime. When running this file directly (e.g. pytest), default to empty.
try:
_INTERNAL
except NameError:
_INTERNAL = {}
DEFAULT_INVOKE_LLM_MODEL = _INTERNAL.get("invoke_llm_model", "openai/gpt-oss-120b")
RATE_LIMIT_PATTERNS = (
"rate limit",
"ratelimit",
"too many requests",
"quota exceeded",
"resource exhausted",
)
def _read_env(name, default=None):
value = os.environ.get(name)
return default if value is None or value == "" else value
def _require_value(value, label):
if value is None or value == "":
raise RuntimeError("%s is required" % label)
return value
def _request_id():
return str(uuid.uuid4())
def _session_execute_url():
backend_url = _read_env("BACKEND_URL", "https://backend.composio.dev").rstrip("/")
session_id = _require_value(
_read_env("COMPOSIO_TOOLROUTER_SESSION_ID"),
"COMPOSIO_TOOLROUTER_SESSION_ID",
)
encoded_session_id = urllib.parse.quote(session_id, safe="")
return "%s/api/v3/tool_router/session/%s/execute" % (backend_url, encoded_session_id)
def _session_proxy_execute_url():
backend_url = _read_env("BACKEND_URL", "https://backend.composio.dev").rstrip("/")
session_id = _require_value(
_read_env("COMPOSIO_TOOLROUTER_SESSION_ID"),
"COMPOSIO_TOOLROUTER_SESSION_ID",
)
encoded_session_id = urllib.parse.quote(session_id, safe="")
return "%s/api/v3/tool_router/session/%s/proxy_execute" % (
backend_url,
encoded_session_id,
)
def _post_json(url, headers, payload, timeout=120):
body = json.dumps(payload).encode("utf-8")
request = urllib.request.Request(url, data=body, headers=headers, method="POST")
try:
with urllib.request.urlopen(request, timeout=timeout) as response:
return response.status, dict(response.headers), response.read().decode("utf-8")
except urllib.error.HTTPError as error:
return error.code, dict(error.headers), error.read().decode("utf-8")
def _parse_json(text):
if not text:
return {}
return json.loads(text)
def _safe_json(text):
try:
return _parse_json(text)
except json.JSONDecodeError:
return {"raw": text}
def _contains_rate_limit_error(payload):
# Only inspect the API "error" field, not the whole body — otherwise benign
# tool output mentioning "rate limit"/"quota" triggers spurious retries.
if not isinstance(payload, dict):
return False
error = payload.get("error")
if not error:
return False
text = json.dumps(error, default=str).lower()
return any(pattern in text for pattern in RATE_LIMIT_PATTERNS)
def _retry_delay(attempt, delay_ms):
base_delay = max(delay_ms, 0) / 1000.0
if base_delay == 0:
return
# Exponential backoff: double the delay each attempt (parity with Apollo).
backoff = base_delay * (2 ** attempt)
jitter = random.uniform(0, min(backoff * 0.2, 0.5))
time.sleep(backoff + jitter)
def _json_shape(value):
if isinstance(value, dict):
return {key: _json_shape(item) for key, item in value.items()}
if isinstance(value, list):
return [_json_shape(value[0])] if value else []
if value is None:
return "null"
return type(value).__name__
def print_json_structure(value):
print(json.dumps(_json_shape(value), indent=2, sort_keys=True))
def _track_helper_event(*_args, **_kwargs):
return None
def run_composio_tool(
tool_slug,
arguments=None,
retry_params=None,
print_schema_for_tool=True,
*,
account=None,
):
if not tool_slug:
return {}, "tool_slug is required"
api_key = _require_value(_read_env("COMPOSIO_API_KEY"), "COMPOSIO_API_KEY")
retry_config = {"max_retries": 3, "delay_ms": 2000}
if retry_params:
retry_config.update(retry_params)
payload = {
"tool_slug": str(tool_slug).strip().upper(),
"arguments": arguments or {},
}
if account is not None:
payload["account"] = account
headers = {
"Content-Type": "application/json",
"x-api-key": api_key,
"x-request-id": _request_id(),
}
max_retries = int(retry_config.get("max_retries", 3))
delay_ms = int(retry_config.get("delay_ms", 2000))
for attempt in range(max_retries + 1):
try:
status, _headers, text = _post_json(_session_execute_url(), headers, payload)
except (urllib.error.URLError, TimeoutError) as error:
# Network failure (timeout, connection/DNS error). Retry transient
# failures, then surface as the error tuple instead of throwing.
if attempt < max_retries:
_retry_delay(attempt, delay_ms)
continue
return {}, "Composio tool request failed: %s" % error
if status == 429 and attempt < max_retries:
_retry_delay(attempt, delay_ms)
continue
if status >= 400:
response_data = _safe_json(text)
return response_data, "Composio tool execution failed with HTTP %s" % status
try:
response_data = _parse_json(text)
except json.JSONDecodeError as error:
return {"raw": text}, "Failed to parse Composio tool response as JSON: %s" % error
if _contains_rate_limit_error(response_data) and attempt < max_retries:
_retry_delay(attempt, delay_ms)
continue
# A failed tool call returns HTTP 200 with a top-level "error" field;
# surface it as the error tuple element so callers don't read it as success.
if isinstance(response_data, dict) and response_data.get("error"):
return response_data, str(response_data["error"])
if print_schema_for_tool:
print_json_structure(response_data)
return response_data, ""
return {}, "Composio tool execution failed after retries"
def _strip_code_fence(content):
stripped = content.strip()
code_fence = chr(96) * 3
if stripped.startswith(code_fence):
stripped = stripped[3:].strip()
if stripped.lower().startswith("json"):
stripped = stripped[4:].strip()
if stripped.endswith(code_fence):
stripped = stripped[:-3].strip()
elif stripped.lower().startswith("json\n"):
stripped = stripped[5:].strip()
return stripped.strip()
def invoke_llm(query, reasoning_effort=None):
if not query:
return "", "query is required"
system_prompt = (
"You are a generic, smart large language model. "
"When asked to output a JSON, respond only with valid JSON - "
"no other text / code fences / quotes around the JSON."
)
response, error = run_composio_tool(
"COMPOSIO_SEARCH_GROQ_CHAT",
{
"model": DEFAULT_INVOKE_LLM_MODEL,
"messages": [
{"role": "system", "content": system_prompt},
{"role": "user", "content": query},
],
"temperature": 0.5,
},
None,
False,
)
_track_helper_event("invoke_llm", {"reasoning_effort": reasoning_effort})
if error:
return "", error
choices = (response.get("data") or {}).get("choices", "")
if not choices:
return "", "No choices returned from invoke_llm"
first_choice = choices[0] if isinstance(choices, list) else choices
content = (first_choice.get("message") or {}).get("content", "")
if not content:
return "", "No content returned from invoke_llm"
return _strip_code_fence(content), ""
def web_search(query):
if not query:
return "", "query is required"
response, error = run_composio_tool(
"COMPOSIO_SEARCH_EXA_ANSWER",
{"content": query},
None,
False,
)
_track_helper_event("web_search", {})
if error:
return "", error
return (response.get("data") or {}).get("answer", ""), ""
def proxy_execute(
method: Literal["GET", "POST", "PUT", "DELETE", "PATCH"],
endpoint: str,
toolkit: str,
query_params: Optional[Dict[str, str]] = None,
body: Optional[object] = None,
headers: Optional[Dict[str, str]] = None,
) -> tuple[Any, str]:
"""Call a toolkit's API directly when no Composio tool exists.
The session resolves the connected account and injects auth server-side, so
your code never handles raw credentials.
Args:
method: HTTP method to use for the request. Example: "GET"
endpoint: API endpoint to call. Example: "/repos/owner/repo"
toolkit: Name of the toolkit. Example: "GITHUB"
query_params: Query parameters as key-value pairs. Example: {"q": "is:unread"}
body: The request body (required for POST, PUT, and PATCH requests)
headers: HTTP headers as key-value pairs. Example: {"Accept": "application/json"}
Returns:
tuple[Any, str]:
- data: Response data from the API (None if error)
- error: Error message ("" if no error)
"""
# Wrapped end-to-end so the helper always returns a (data, error) tuple
# rather than raising.
try:
valid_methods = ["GET", "POST", "PUT", "DELETE", "PATCH"]
if method.upper() not in valid_methods:
return None, "Invalid HTTP method: " + method
if not endpoint.strip():
return None, "Endpoint cannot be empty"
if not toolkit.strip():
return None, "Toolkit cannot be empty"
if query_params is not None and not isinstance(query_params, dict):
return None, (
"Invalid query_params type: expected dict or None, got "
+ type(query_params).__name__
)
if headers is not None and not isinstance(headers, dict):
return None, (
"Invalid headers type: expected dict or None, got "
+ type(headers).__name__
)
if method.upper() in ["POST", "PUT", "PATCH"] and body is None:
return None, "Body is required for " + method.upper() + " requests"
if method.upper() in ["GET", "DELETE"] and body is not None:
return None, "Body should not be provided for " + method.upper() + " requests"
api_key = _read_env("COMPOSIO_API_KEY")
if not api_key:
return None, "Missing environment variable COMPOSIO_API_KEY"
if not _read_env("COMPOSIO_TOOLROUTER_SESSION_ID"):
return None, "Missing environment variable COMPOSIO_TOOLROUTER_SESSION_ID"
# Convert query_params and headers dicts to the flat parameters array.
parameters = []
if query_params:
for key, value in query_params.items():
parameters.append({"name": key, "value": str(value), "type": "query"})
if headers:
for key, value in headers.items():
parameters.append({"name": key, "value": str(value), "type": "header"})
payload = {
"toolkit_slug": toolkit.lower(),
"endpoint": endpoint,
"method": method.upper(),
}
if parameters:
payload["parameters"] = parameters
if body is not None:
payload["body"] = body
request_headers = {
"Content-Type": "application/json",
"x-api-key": api_key,
"x-request-id": _request_id(),
}
status, _response_headers, text = _post_json(
_session_proxy_execute_url(), request_headers, payload
)
# Handle HTTP errors explicitly. Always surface a non-empty message so a
# >=400 response never looks like success (an empty error/message field
# must not win over the default).
if status >= 400:
error_msg = "HTTP " + str(status) + " Error"
try:
error_data = json.loads(text)
if isinstance(error_data, dict):
error_msg = (
error_data.get("error") or error_data.get("message") or error_msg
)
except (ValueError, TypeError):
if text:
sanitized = text[:200].replace("\n", " ").strip()
error_msg = "HTTP " + str(status) + ": " + sanitized
return None, str(error_msg)
response_data = json.loads(text)
# The session wraps the proxied response as {data, status, headers}; the
# toolkit's own API may still report a >=400 status inside that envelope.
# `status` can arrive as a string or null, so coerce it before comparing
# — a bare `>= 400` against a non-int would raise and mask a valid result.
if isinstance(response_data, dict):
try:
api_status = int(response_data.get("status", 200))
except (TypeError, ValueError):
api_status = 200
if api_status >= 400:
error_msg = "API request failed"
if isinstance(response_data.get("data"), dict):
error_msg = response_data["data"].get(
"message", response_data["data"].get("error", error_msg)
)
return response_data, "API returned status " + str(api_status) + ": " + str(error_msg)
return response_data.get("data"), ""
return response_data, ""
except Exception as error:
return None, "Failed to execute proxy request: " + str(error)