docs(plugins): Add model providers section to plugin documentation
linuztx committed
Mar 12, 2026 at 08:51 UTC
b0068966d3e52ec8aae212f26754483155fb1e01
1 file changed
+33
-3
docs/agents/AGENTS.plugins.md
+33
-3
@@ -28,6 +28,8 @@ usr/plugins/<plugin_name>/
28
├── default_config.yaml # Optional: fallback settings defaults
29
├── README.md # Optional: shown in Plugin List UI
30
├── LICENSE # Optional: shown in Plugin List UI
31
+├── conf/
32
+│ └── model_providers.yaml # Optional: add or override model providers
33
├── api/ # API handlers (ApiHandler subclasses)
34
├── tools/ # Agent tools (Tool subclasses)
35
├── helpers/ # Shared Python logic
@@ -106,7 +108,35 @@ See [Notifications](../developer/notifications.md) for the full API.
108
4. usr/plugins/<name>/config.json
109
5. plugins/<name>/default_config.yaml (fallback defaults)
110
109
-## 5. Plugin Activation Model
111
+## 5. Model Providers
112
+
113
+Plugins can add or override model providers by placing a `conf/model_providers.yaml` inside their plugin directory. The file follows the same format as the main `conf/model_providers.yaml`.
114
+
115
+At startup (and whenever a plugin is enabled/disabled), the system:
116
+1. Loads the base `conf/model_providers.yaml`.
117
+2. Discovers `conf/model_providers.yaml` from all enabled plugins.
118
+3. Merges them in order — matching provider IDs are overwritten, new IDs are appended.
119
+
120
+Example plugin provider file (`usr/plugins/my_plugin/conf/model_providers.yaml`):
121
+```yaml
122
+chat:
123
+ my_custom_provider:
124
+ name: My Custom LLM
125
+ litellm_provider: openai
126
+ kwargs:
127
+ api_base: https://my-llm.example.com/v1
128
+
129
+embedding:
130
+ my_custom_embed:
131
+ name: My Embeddings
132
+ litellm_provider: openai
133
+ kwargs:
134
+ api_base: https://my-embed.example.com/v1
135
+```
136
+
137
+---
138
+
139
+## 6. Plugin Activation Model
140
141
- Global and scoped activation are independent, with no inheritance between scopes.
142
- Activation flags are files: `.toggle-1` (ON) and `.toggle-0` (OFF).
@@ -116,7 +146,7 @@ See [Notifications](../developer/notifications.md) for the full API.
146
147
---
148
119
-## 6. Routes
149
+## 7. Routes
150
151
| Route | Purpose |
152
|---|---|
@@ -126,7 +156,7 @@ See [Notifications](../developer/notifications.md) for the full API.
156
157
---
158
129
-## 7. Plugin Index & Community Sharing
159
+## 8. Plugin Index & Community Sharing
160
161
The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins that lists plugins available to the Agent Zero community. Plugins listed there can be discovered and installed by other users.
162