Model Pool
How City manages the model catalog and how Agents bind to models
City owns the model catalog through the Federation AIService. Agents do not embed provider keys or model definitions directly. Instead, they bind to models by ID, and City resolves the ID to a live model instance at runtime.
How it works
- City registers model providers (OpenAI, Anthropic, Google, local models, etc.)
- Each provider exposes capabilities and model IDs
- The Federation AIService maintains a unified catalog
- Agents bind to a model ID like
"default"or"quality" - At runtime, the ID is resolved to a live model instance
Model binding
For Desktop- or CLI-managed Agents, the binding is stored in the user-level Agent configuration:
{
"execution": {
"type": "api",
"model_id": "quality",
"reasoning_effort": "high"
}
}In Desktop, open Model in the Agent configuration to select its default model and reasoning effort. Choices come from the model's published capabilities. Models without configurable reasoning hide the selector. Choosing Follow model default removes execution.reasoning_effort.
reasoning_effort is optional; high in this example must be a supported effort. Explicit session or execution reasoning takes precedence, followed by the Agent default and then the model default. New sessions, background tasks and delegated work inherit the effort when using the Agent's default model. Switching models retains only supported efforts; otherwise the model default applies. An Agent's default effort applies only to its configured default model.
Desktop validates the selected model and reasoning effort when saving an Agent configuration. The default model applies to new sessions; existing sessions retain their model bindings and settings, and an active turn keeps its configuration. After switching accounts or Federation targets, subsequent execution resolves the bound model's context window and reasoning capabilities using the current identity. If the model is unavailable, execution returns an error and requires an available model selection. CLI configuration changes apply when the Agent is next assembled.
Desktop memo text processing and task previews use the default text model from Settings. For Federation models, these features share the current sign-in identity and host network settings with Agents.
For SDK projects, the model is passed directly to the constructor or session.
Provider management
City handles:
- Provider registration and authentication
- Model capability discovery
- Usage metering per provider
- Failover between providers
Continue with: