Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import json |
| 2 | import os |
| 3 | import random |
| 4 | import time |
| 5 | import urllib.error |
| 6 | import urllib.parse |
| 7 | import urllib.request |
| 8 | import uuid |
| 9 | from typing import Any, Dict, Literal, Optional |
| 10 | |
| 11 | |
| 12 | # Config is injected by the SDK via an `_INTERNAL` dict in a prologue prepended |
| 13 | # at runtime. When running this file directly (e.g. pytest), default to empty. |
| 14 | try: |
| 15 | _INTERNAL |
| 16 | except NameError: |
| 17 | _INTERNAL = {} |
| 18 | |
| 19 | |
| 20 | DEFAULT_INVOKE_LLM_MODEL = _INTERNAL.get("invoke_llm_model", "openai/gpt-oss-120b") |
| 21 | RATE_LIMIT_PATTERNS = ( |
| 22 | "rate limit", |
| 23 | "ratelimit", |
| 24 | "too many requests", |
| 25 | "quota exceeded", |
| 26 | "resource exhausted", |
| 27 | ) |
| 28 | |
| 29 | |
| 30 | def _read_env(name, default=None): |
| 31 | value = os.environ.get(name) |
| 32 | return default if value is None or value == "" else value |
| 33 | |
| 34 | |
| 35 | def _require_value(value, label): |
| 36 | if value is None or value == "": |
| 37 | raise RuntimeError("%s is required" % label) |
| 38 | return value |
| 39 | |
| 40 | |
| 41 | def _request_id(): |
| 42 | return str(uuid.uuid4()) |
| 43 | |
| 44 | |
| 45 | def _session_execute_url(): |
| 46 | backend_url = _read_env("BACKEND_URL", "https://backend.composio.dev").rstrip("/") |
| 47 | session_id = _require_value( |
| 48 | _read_env("COMPOSIO_TOOLROUTER_SESSION_ID"), |
| 49 | "COMPOSIO_TOOLROUTER_SESSION_ID", |
| 50 | ) |
| 51 | encoded_session_id = urllib.parse.quote(session_id, safe="") |
| 52 | return "%s/api/v3/tool_router/session/%s/execute" % (backend_url, encoded_session_id) |
| 53 | |
| 54 | |
| 55 | def _session_proxy_execute_url(): |
| 56 | backend_url = _read_env("BACKEND_URL", "https://backend.composio.dev").rstrip("/") |
| 57 | session_id = _require_value( |
| 58 | _read_env("COMPOSIO_TOOLROUTER_SESSION_ID"), |
| 59 | "COMPOSIO_TOOLROUTER_SESSION_ID", |
| 60 | ) |
| 61 | encoded_session_id = urllib.parse.quote(session_id, safe="") |
| 62 | return "%s/api/v3/tool_router/session/%s/proxy_execute" % ( |
| 63 | backend_url, |
| 64 | encoded_session_id, |
| 65 | ) |
| 66 | |
| 67 | |
| 68 | def _post_json(url, headers, payload, timeout=120): |
| 69 | body = json.dumps(payload).encode("utf-8") |
| 70 | request = urllib.request.Request(url, data=body, headers=headers, method="POST") |
| 71 | try: |
| 72 | with urllib.request.urlopen(request, timeout=timeout) as response: |
| 73 | return response.status, dict(response.headers), response.read().decode("utf-8") |
| 74 | except urllib.error.HTTPError as error: |
| 75 | return error.code, dict(error.headers), error.read().decode("utf-8") |
| 76 | |
| 77 | |
| 78 | def _parse_json(text): |
| 79 | if not text: |
| 80 | return {} |
| 81 | return json.loads(text) |
| 82 | |
| 83 | |
| 84 | def _safe_json(text): |
| 85 | try: |
| 86 | return _parse_json(text) |
| 87 | except json.JSONDecodeError: |
| 88 | return {"raw": text} |
| 89 | |
| 90 | |
| 91 | def _contains_rate_limit_error(payload): |
| 92 | # Only inspect the API "error" field, not the whole body — otherwise benign |
| 93 | # tool output mentioning "rate limit"/"quota" triggers spurious retries. |
| 94 | if not isinstance(payload, dict): |
| 95 | return False |
| 96 | error = payload.get("error") |
| 97 | if not error: |
| 98 | return False |
| 99 | text = json.dumps(error, default=str).lower() |
| 100 | return any(pattern in text for pattern in RATE_LIMIT_PATTERNS) |
| 101 | |
| 102 | |
| 103 | def _retry_delay(attempt, delay_ms): |
| 104 | base_delay = max(delay_ms, 0) / 1000.0 |
| 105 | if base_delay == 0: |
| 106 | return |
| 107 | # Exponential backoff: double the delay each attempt (parity with Apollo). |
| 108 | backoff = base_delay * (2 ** attempt) |
| 109 | jitter = random.uniform(0, min(backoff * 0.2, 0.5)) |
| 110 | time.sleep(backoff + jitter) |
| 111 | |
| 112 | |
| 113 | def _json_shape(value): |
| 114 | if isinstance(value, dict): |
| 115 | return {key: _json_shape(item) for key, item in value.items()} |
| 116 | if isinstance(value, list): |
| 117 | return [_json_shape(value[0])] if value else [] |
| 118 | if value is None: |
| 119 | return "null" |
| 120 | return type(value).__name__ |
| 121 | |
| 122 | |
| 123 | def print_json_structure(value): |
| 124 | print(json.dumps(_json_shape(value), indent=2, sort_keys=True)) |
| 125 | |
| 126 | |
| 127 | def _track_helper_event(*_args, **_kwargs): |
| 128 | return None |
| 129 | |
| 130 | |
| 131 | def _is_input_required(payload): |
| 132 | return isinstance(payload, dict) and payload.get("result_type") == "input_required" |
| 133 | |
| 134 | |
| 135 | def _input_required_error(subject, payload): |
| 136 | # The message names the call and counts the questions. `request_state` is |
| 137 | # opaque continuation state, so it stays out of the message. |
| 138 | input_requests = payload.get("input_requests") |
| 139 | count = len(input_requests) if isinstance(input_requests, dict) else 0 |
| 140 | return "%s requires user input before it can run (%d input request%s) and was not executed" % ( |
| 141 | subject, |
| 142 | count, |
| 143 | "" if count == 1 else "s", |
| 144 | ) |
| 145 | |
| 146 | |
| 147 | def run_composio_tool( |
| 148 | tool_slug, |
| 149 | arguments=None, |
| 150 | retry_params=None, |
| 151 | print_schema_for_tool=True, |
| 152 | *, |
| 153 | account=None, |
| 154 | ): |
| 155 | if not tool_slug: |
| 156 | return {}, "tool_slug is required" |
| 157 | |
| 158 | api_key = _require_value(_read_env("COMPOSIO_API_KEY"), "COMPOSIO_API_KEY") |
| 159 | retry_config = {"max_retries": 3, "delay_ms": 2000} |
| 160 | if retry_params: |
| 161 | retry_config.update(retry_params) |
| 162 | |
| 163 | payload = { |
| 164 | "tool_slug": str(tool_slug).strip().upper(), |
| 165 | "arguments": arguments or {}, |
| 166 | } |
| 167 | if account is not None: |
| 168 | payload["account"] = account |
| 169 | |
| 170 | headers = { |
| 171 | "Content-Type": "application/json", |
| 172 | "x-api-key": api_key, |
| 173 | "x-request-id": _request_id(), |
| 174 | } |
| 175 | max_retries = int(retry_config.get("max_retries", 3)) |
| 176 | delay_ms = int(retry_config.get("delay_ms", 2000)) |
| 177 | |
| 178 | for attempt in range(max_retries + 1): |
| 179 | try: |
| 180 | status, _headers, text = _post_json(_session_execute_url(), headers, payload) |
| 181 | except (urllib.error.URLError, TimeoutError) as error: |
| 182 | # Network failure (timeout, connection/DNS error). Never retry it: |
| 183 | # the backend may already have run the tool and does not deduplicate |
| 184 | # executions, so re-sending can repeat the side effect. Surface it as |
| 185 | # the error tuple instead of throwing. |
| 186 | return {}, "Composio tool request failed: %s" % error |
| 187 | |
| 188 | if status == 429 and attempt < max_retries: |
| 189 | _retry_delay(attempt, delay_ms) |
| 190 | continue |
| 191 | |
| 192 | if status >= 400: |
| 193 | response_data = _safe_json(text) |
| 194 | return response_data, "Composio tool execution failed with HTTP %s" % status |
| 195 | |
| 196 | try: |
| 197 | response_data = _parse_json(text) |
| 198 | except json.JSONDecodeError as error: |
| 199 | return {"raw": text}, "Failed to parse Composio tool response as JSON: %s" % error |
| 200 | |
| 201 | if _contains_rate_limit_error(response_data) and attempt < max_retries: |
| 202 | _retry_delay(attempt, delay_ms) |
| 203 | continue |
| 204 | |
| 205 | # The call needs the user's input (an approval, for example) and did not |
| 206 | # run. Hand back the questions, without `request_state`, as an error. |
| 207 | if _is_input_required(response_data): |
| 208 | return ( |
| 209 | { |
| 210 | "result_type": "input_required", |
| 211 | "input_requests": response_data.get("input_requests") or {}, |
| 212 | }, |
| 213 | _input_required_error("Tool %s" % payload["tool_slug"], response_data), |
| 214 | ) |
| 215 | |
| 216 | # A failed tool call returns HTTP 200. `result_type` says it failed even |
| 217 | # when "error" is null or empty; a response without `result_type` is |
| 218 | # failed when it carries an "error". Surface either as the error tuple |
| 219 | # element so callers don't read it as success. |
| 220 | if isinstance(response_data, dict) and ( |
| 221 | response_data.get("result_type") == "failed" or response_data.get("error") |
| 222 | ): |
| 223 | return response_data, str( |
| 224 | response_data.get("error") or "Composio tool execution failed without an error message" |
| 225 | ) |
| 226 | |
| 227 | if print_schema_for_tool: |
| 228 | print_json_structure(response_data) |
| 229 | return response_data, "" |
| 230 | |
| 231 | return {}, "Composio tool execution failed after retries" |
| 232 | |
| 233 | |
| 234 | def _strip_code_fence(content): |
| 235 | stripped = content.strip() |
| 236 | code_fence = chr(96) * 3 |
| 237 | if stripped.startswith(code_fence): |
| 238 | stripped = stripped[3:].strip() |
| 239 | if stripped.lower().startswith("json"): |
| 240 | stripped = stripped[4:].strip() |
| 241 | if stripped.endswith(code_fence): |
| 242 | stripped = stripped[:-3].strip() |
| 243 | elif stripped.lower().startswith("json\n"): |
| 244 | stripped = stripped[5:].strip() |
| 245 | return stripped.strip() |
| 246 | |
| 247 | |
| 248 | def invoke_llm(query, reasoning_effort=None): |
| 249 | if not query: |
| 250 | return "", "query is required" |
| 251 | |
| 252 | system_prompt = ( |
| 253 | "You are a generic, smart large language model. " |
| 254 | "When asked to output a JSON, respond only with valid JSON - " |
| 255 | "no other text / code fences / quotes around the JSON." |
| 256 | ) |
| 257 | response, error = run_composio_tool( |
| 258 | "COMPOSIO_SEARCH_GROQ_CHAT", |
| 259 | { |
| 260 | "model": DEFAULT_INVOKE_LLM_MODEL, |
| 261 | "messages": [ |
| 262 | {"role": "system", "content": system_prompt}, |
| 263 | {"role": "user", "content": query}, |
| 264 | ], |
| 265 | "temperature": 0.5, |
| 266 | }, |
| 267 | None, |
| 268 | False, |
| 269 | ) |
| 270 | _track_helper_event("invoke_llm", {"reasoning_effort": reasoning_effort}) |
| 271 | |
| 272 | if error: |
| 273 | return "", error |
| 274 | |
| 275 | choices = (response.get("data") or {}).get("choices", "") |
| 276 | if not choices: |
| 277 | return "", "No choices returned from invoke_llm" |
| 278 | |
| 279 | first_choice = choices[0] if isinstance(choices, list) else choices |
| 280 | content = (first_choice.get("message") or {}).get("content", "") |
| 281 | if not content: |
| 282 | return "", "No content returned from invoke_llm" |
| 283 | return _strip_code_fence(content), "" |
| 284 | |
| 285 | |
| 286 | def web_search(query): |
| 287 | if not query: |
| 288 | return "", "query is required" |
| 289 | |
| 290 | response, error = run_composio_tool( |
| 291 | "COMPOSIO_SEARCH_EXA_ANSWER", |
| 292 | {"content": query}, |
| 293 | None, |
| 294 | False, |
| 295 | ) |
| 296 | _track_helper_event("web_search", {}) |
| 297 | |
| 298 | if error: |
| 299 | return "", error |
| 300 | return (response.get("data") or {}).get("answer", ""), "" |
| 301 | |
| 302 | |
| 303 | def proxy_execute( |
| 304 | method: Literal["GET", "POST", "PUT", "DELETE", "PATCH"], |
| 305 | endpoint: str, |
| 306 | toolkit: str, |
| 307 | query_params: Optional[Dict[str, str]] = None, |
| 308 | body: Optional[object] = None, |
| 309 | headers: Optional[Dict[str, str]] = None, |
| 310 | ) -> tuple[Any, str]: |
| 311 | """Call a toolkit's API directly when no Composio tool exists. |
| 312 | |
| 313 | The session resolves the connected account and injects auth server-side, so |
| 314 | your code never handles raw credentials. |
| 315 | |
| 316 | Args: |
| 317 | method: HTTP method to use for the request. Example: "GET" |
| 318 | endpoint: API endpoint to call. Example: "/repos/owner/repo" |
| 319 | toolkit: Name of the toolkit. Example: "GITHUB" |
| 320 | query_params: Query parameters as key-value pairs. Example: {"q": "is:unread"} |
| 321 | body: The request body (required for POST, PUT, and PATCH requests) |
| 322 | headers: HTTP headers as key-value pairs. Example: {"Accept": "application/json"} |
| 323 | |
| 324 | Returns: |
| 325 | tuple[Any, str]: |
| 326 | - data: Response data from the API (None if error) |
| 327 | - error: Error message ("" if no error) |
| 328 | """ |
| 329 | # Wrapped end-to-end so the helper always returns a (data, error) tuple |
| 330 | # rather than raising. |
| 331 | try: |
| 332 | valid_methods = ["GET", "POST", "PUT", "DELETE", "PATCH"] |
| 333 | if method.upper() not in valid_methods: |
| 334 | return None, "Invalid HTTP method: " + method |
| 335 | |
| 336 | if not endpoint.strip(): |
| 337 | return None, "Endpoint cannot be empty" |
| 338 | |
| 339 | if not toolkit.strip(): |
| 340 | return None, "Toolkit cannot be empty" |
| 341 | |
| 342 | if query_params is not None and not isinstance(query_params, dict): |
| 343 | return None, ( |
| 344 | "Invalid query_params type: expected dict or None, got " |
| 345 | + type(query_params).__name__ |
| 346 | ) |
| 347 | |
| 348 | if headers is not None and not isinstance(headers, dict): |
| 349 | return None, ( |
| 350 | "Invalid headers type: expected dict or None, got " |
| 351 | + type(headers).__name__ |
| 352 | ) |
| 353 | |
| 354 | if method.upper() in ["POST", "PUT", "PATCH"] and body is None: |
| 355 | return None, "Body is required for " + method.upper() + " requests" |
| 356 | |
| 357 | if method.upper() in ["GET", "DELETE"] and body is not None: |
| 358 | return None, "Body should not be provided for " + method.upper() + " requests" |
| 359 | |
| 360 | api_key = _read_env("COMPOSIO_API_KEY") |
| 361 | if not api_key: |
| 362 | return None, "Missing environment variable COMPOSIO_API_KEY" |
| 363 | if not _read_env("COMPOSIO_TOOLROUTER_SESSION_ID"): |
| 364 | return None, "Missing environment variable COMPOSIO_TOOLROUTER_SESSION_ID" |
| 365 | |
| 366 | # Convert query_params and headers dicts to the flat parameters array. |
| 367 | parameters = [] |
| 368 | if query_params: |
| 369 | for key, value in query_params.items(): |
| 370 | parameters.append({"name": key, "value": str(value), "type": "query"}) |
| 371 | if headers: |
| 372 | for key, value in headers.items(): |
| 373 | parameters.append({"name": key, "value": str(value), "type": "header"}) |
| 374 | |
| 375 | payload = { |
| 376 | "toolkit_slug": toolkit.lower(), |
| 377 | "endpoint": endpoint, |
| 378 | "method": method.upper(), |
| 379 | } |
| 380 | if parameters: |
| 381 | payload["parameters"] = parameters |
| 382 | if body is not None: |
| 383 | payload["body"] = body |
| 384 | |
| 385 | request_headers = { |
| 386 | "Content-Type": "application/json", |
| 387 | "x-api-key": api_key, |
| 388 | "x-request-id": _request_id(), |
| 389 | } |
| 390 | |
| 391 | status, _response_headers, text = _post_json( |
| 392 | _session_proxy_execute_url(), request_headers, payload |
| 393 | ) |
| 394 | |
| 395 | # Handle HTTP errors explicitly. Always surface a non-empty message so a |
| 396 | # >=400 response never looks like success (an empty error/message field |
| 397 | # must not win over the default). |
| 398 | if status >= 400: |
| 399 | error_msg = "HTTP " + str(status) + " Error" |
| 400 | try: |
| 401 | error_data = json.loads(text) |
| 402 | if isinstance(error_data, dict): |
| 403 | error_msg = ( |
| 404 | error_data.get("error") or error_data.get("message") or error_msg |
| 405 | ) |
| 406 | except (ValueError, TypeError): |
| 407 | if text: |
| 408 | sanitized = text[:200].replace("\n", " ").strip() |
| 409 | error_msg = "HTTP " + str(status) + ": " + sanitized |
| 410 | return None, str(error_msg) |
| 411 | |
| 412 | response_data = json.loads(text) |
| 413 | |
| 414 | # The call needs the user's input (an approval, for example) and was |
| 415 | # never proxied: it has no status or data to return. |
| 416 | if _is_input_required(response_data): |
| 417 | return None, _input_required_error( |
| 418 | "%s proxy call for toolkit %s" % (method.upper(), toolkit.lower()), |
| 419 | response_data, |
| 420 | ) |
| 421 | |
| 422 | # The session wraps the proxied response as {data, status, headers}; the |
| 423 | # toolkit's own API may still report a >=400 status inside that envelope. |
| 424 | # `status` can arrive as a string or null, so coerce it before comparing |
| 425 | # — a bare `>= 400` against a non-int would raise and mask a valid result. |
| 426 | if isinstance(response_data, dict): |
| 427 | try: |
| 428 | api_status = int(response_data.get("status", 200)) |
| 429 | except (TypeError, ValueError): |
| 430 | api_status = 200 |
| 431 | if api_status >= 400: |
| 432 | error_msg = "API request failed" |
| 433 | if isinstance(response_data.get("data"), dict): |
| 434 | error_msg = response_data["data"].get( |
| 435 | "message", response_data["data"].get("error", error_msg) |
| 436 | ) |
| 437 | return response_data, "API returned status " + str(api_status) + ": " + str(error_msg) |
| 438 | return response_data.get("data"), "" |
| 439 | |
| 440 | return response_data, "" |
| 441 | except Exception as error: |
| 442 | return None, "Failed to execute proxy request: " + str(error) |