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, providers, 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 project stores a modelId
  • not provider config
  • not API keys
  • not a local model instance

The right mental model is:

downcity.json.execution.modelId
  -> Downcity reads and validates it
  -> Federation AIService resolves the target model
  -> Agent runtime executes with that model

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