Skip to main content
A provider adapts Composio tools to the format your AI framework expects. Write one, and any framework can call Composio’s 1000+ tools. This guide shows you how to build your own in TypeScript.

Provider architecture

A provider does three things:
  • Transforms tool format: converts Composio tools into the shape your AI platform expects.
  • Executes tools: runs tool calls and returns results.
  • Adds platform helpers: exposes convenience methods specific to your platform.
There are two kinds, depending on whether the target platform runs its own agent loop: Both extend BaseProvider:

Non-agentic provider

A non-agentic provider extends BaseNonAgenticProvider. You supply a name, wrapTool, and wrapTools, and call the built-in executeTool when you’re ready to run a tool.

Agentic provider

An agentic provider extends BaseAgenticProvider. The difference from the non-agentic case: wrapTool and wrapTools receive an executeToolFn, which you embed in each tool so the framework’s agent can run the tool itself.

Build Zod schemas

If your framework expects Zod v4 schemas, import jsonSchemaToZod or jsonSchemaToZodShape from @composio/json-schema-to-zod/v4. This entry builds classic Zod v4 schemas and requires Zod 4.1.13 or newer. It stores schema annotations in metadata so z.toJSONSchema() preserves them. The root @composio/json-schema-to-zod entry builds Zod v3 schemas.

Support strict tool schemas

If your platform supports OpenAI-compatible strict tool schemas, use toStrictJsonSchema() to normalize each tool’s input schema. The result keeps optional parameters available by making them required and nullable. Before execution, use omitNullToolArguments() to remove a null that represents an omitted optional parameter while preserving fields whose original schema accepts null.
When strict.unsupported isn’t empty, send the original schema without strict mode and log the reported paths. Strict mode can’t represent arbitrary-key objects, unsupported intersections, tuple-style arrays, or unresolved references without narrowing the tool’s accepted input.

Use your provider

Pass an instance to Composio via the provider option. Every tool you fetch comes back in your custom format.

Provider state and context

A provider is a class, so it can hold state. Use the constructor for config, and instance fields for caches or counters.

Add behavior with composition

Don’t subclass a concrete provider to add analytics, retries, or other cross-cutting behavior. Hold a provider instance and delegate to it instead. This avoids making your class satisfy every overload that the provider exposes.
Pass the underlying provider to Composio, then call the wrapper from your manual tool-call loop.

Best practices

  • Keep providers focused: each provider should target one platform.
  • Handle errors gracefully: catch and transform errors from tool execution.
  • Follow platform conventions: adopt the naming and structure of the target platform.
  • Cache transformed tools: reuse wrapped tools instead of rebuilding them.
  • Add helper methods: expose convenience methods for common platform operations.
  • Document your provider: describe its features and usage.
  • Set a meaningful name: it’s used for telemetry insights.