Merge pull request #155 from stanislavHamara/new-provider-docs

Add docs on how to add a new provider

Author: rumpl

README.md

@@ -39,7 +39,7 @@ Many more examples can be found [here](/examples/README.md)!
 
 ### Improving an agent with MCP tools
 
-`cagent` supports MCP servers, enabling agents to use a wide variety of external tools and services.  
+`cagent` supports MCP servers, enabling agents to use a wide variety of external tools and services.
 
 It supports three transport types: `stdio`, `http` and `sse`.
 
@@ -62,9 +62,9 @@ agents:
         ref: docker:duckduckgo # stdio transport
 ```
 
-When using a containerized server via the Docker MCP gateway, you can configure any required settings/secrets/authentication using the [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#example-use-the-github-official-mcp-server) in Docker Desktop.  
+When using a containerized server via the Docker MCP gateway, you can configure any required settings/secrets/authentication using the [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#example-use-the-github-official-mcp-server) in Docker Desktop.
 
-Aside from the containerized MCP severs the Docker MCP Gateway provides, any standard MCP server can be used with cagent!  
+Aside from the containerized MCP severs the Docker MCP Gateway provides, any standard MCP server can be used with cagent!
 
 Here's an example similar to the above but adding `read_file` and `write_file` tools from the `rust-mcp-filesystem` MCP server:
 
@@ -194,7 +194,7 @@ models:
     model: ai/qwen3
     max_tokens: 8192
     provider_opts:
-      runtime_flags: ["--ngl=33", "--repeat-penalty=1.2", ...]  # or comma/space-separated string
+      runtime_flags: ["--ngl=33", "--repeat-penalty=1.2", ...] # or comma/space-separated string
 ```
 
 The default base_url `cagent` will use for dmr providers is `http://localhost:12434/engines/llama.cpp/v1`. DMR itself might need to be enabled via [Docker Desktop's settings](https://docs.docker.com/ai/model-runner/get-started/#enable-dmr-in-docker-desktop) on MacOS and Windows, and via command line on [Docker CE on Linux](https://docs.docker.com/ai/model-runner/get-started/#enable-dmr-in-docker-engine).

docs/CONTRIBUTING.md

@@ -85,6 +85,10 @@ improvements to the code. It can also fix issues and implement new features!
 
 More info about the architecture behind `cagent` can be found [here](/docs/architecture.md)
 
+## Add a new model provider
+
+More details on how to add a new model provider can be found in [PROVIDERS.md](/docs/PROVIDERS.md)
+
 ## Opening issues
 
 Issues can be opened on our repo [here](https://github.com/docker/cagent/issues).  

docs/PROVIDERS.md

@@ -0,0 +1,65 @@
+# Adding a new provider to Cagent
+
+## Add provider alias
+
+Add a new `Alias` to `ProviderAliases` [`pkg/model/provider/provider.go`](https://github.com/docker/cagent/blob/main/pkg/model/provider/provider.go)
+
+```go
+var ProviderAliases = map[string]Alias{
+ "requesty": {
+  ApiType:     "openai",
+  BaseURL:     "https://router.requesty.ai/v1",
+  TokenEnvVar: "REQUESTY_API_KEY",
+ },
+ "azure": {
+  ApiType:     "openai",
+  TokenEnvVar: "AZURE_API_KEY",
+ },
+ "YOUR_PROVIDER": {
+    ApiType: "openai"
+    TokenEnvVar: "YOUR_PROVIDER_API_KEY"
+    BaseURL: "https://your-provider.ai/v1"
+ }
+}
+```
+
+## Add custom config if needed (optional)
+
+If your provider requires custom config, like Azure's `api_version`
+
+```yaml
+models:
+  azure_model:
+    provider: azure
+    model: gpt-4o
+    base_url: https://your-llm.openai.azure.com
+    provider_opts:
+      api_version: 2024-12-01-preview
+  # custom option example
+  your_model:
+    provider: your_provider
+    model: gpt-4o
+    provider_opts:
+      your_custom_option: your_custom_value
+```
+
+edit [`pkg/model/provider/openai/client.go`](https://github.com/docker/cagent/blob/main/pkg/model/provider/openai/client.go)
+
+```go
+switch cfg.Provider { //nolint:gocritic
+   case "azure":
+     if apiVersion, exists := cfg.ProviderOpts["api_version"]; exists {
+       slog.Debug("Setting API version", "api_version", apiVersion)
+       if apiVersionStr, ok := apiVersion.(string); ok {
+          openaiConfig.APIVersion = apiVersionStr
+       }
+      }
+   case "your_provider":
+     if yourCustomOption, exists := cfg.ProviderOpts["your_custom_option"]; exists {
+       slog.Debug("Setting your custom option", "your_custom_option", yourCustomOption)
+       if yourCustomOptionStr, ok := yourCustomOption.(string); ok {
+        openaiConfig.yourCustomOption = yourCustomOptionStr
+       }
+      }
+   }
+```