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.
Both extend
BaseProvider:
Non-agentic provider
A non-agentic provider extendsBaseNonAgenticProvider. 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 extendsBaseAgenticProvider. 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, importjsonSchemaToZod 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, usetoStrictJsonSchema() 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.
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 toComposio 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.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.