Create Your First Agent

Prerequisites

Before you start, make sure you have:

• city installed
• a project directory
• at least one usable model in the global city model pool

If your model pool is not ready yet, set that up first and then come back here.

Initialize the project

Run this from the project root:

city agent create .

The CLI will ask for:

• the agent name
• the primary model ID
• which chat channels you want to enable

The most important input here is the model ID, because it directly affects whether the project can start correctly later.

What gets created

A minimal project usually includes:

• PROFILE.md
• SOUL.md
• downcity.json
• .downcity/
• downcity.schema.json

If the target directory already contains some files, the CLI tries to avoid meaningless overwrites and will ask before replacing downcity.json where needed.

The three things to check first

1. Is downcity.json.execution.modelId the model you actually want?
2. Does PROFILE.md clearly define the agent role?
3. Do you really want chat channels enabled yet?

If you are only validating the local execution path, it is completely fine to start with no chat channels enabled.

Minimal runnable config

{
  "name": "my-agent",
  "version": "1.0.0",
  "execution": {
    "type": "api",
    "modelId": "quality"
  },
  "services": {}
}

This is the best starting point for first-time verification because it minimizes moving parts and makes troubleshooting much easier.

Common misunderstandings

"create configures everything automatically"

It does not.

It creates the project scaffold and the minimum runtime structure. It does not automatically create your global model pool or external chat credentials.

"Selecting a chat channel means messaging already works"

Not yet.

For channels to work, you still need:

• a real global channel account
• the correct channelAccountId binding
• a restarted and running agent

Next:

• Start and stop an Agent
• Chat with an Agent