Integration Patterns

Agent and Federation AIService

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

Agent and Federation AIService

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.doStream() directly
  -> Federation AIService routes to the AIChannel and upstream protocol

Embed in a Node App

Recommended pattern for creating and using a local Agent directly inside a Node.js application

Multiple Agents in One Repo

Use multiple agentIds to isolate different SDK Agents in the same project directory

Table of Contents

Agent and Federation AIServiceThe most important takeaway