Agent and Federation AIService

Understand the model ownership boundary between Agent, Downcity, City, and AIService, and how to use them together

If you are using Agent inside a normal Downcity project, the model usually should not be owned directly by the Agent project.

Split responsibilities across four layers:

Federation AIService: owns the model catalog, AIChannels, API keys, and model routing
Downcity: connects to City, reads the catalog, validates and resolves modelId
Agent project: stores only execution.modelId
@downcity/agent session: actually executes prompts

The most important takeaway

In Downcity integration mode:

the CLI global database stores a modelId
not AIChannel config
not API keys
not a local model instance

The right mental model is:

global downcity.db: agent.execution.modelId
  -> Downcity reads and validates it
  -> City SDK creates an executable CityModel
  -> Agent calls CityModel.stream() through Downcity Model Protocol
  -> Federation AIService routes to the AIChannel and upstream protocol