[docs] API server: clarify the `:agent` parameter in session endpoints

[k33g]

Description

The API server documentation documents the following endpoints:

/api/sessions/:id/agent/:agent
/api/sessions/:id/agent/:agent/:name

However, it does not explain what the :agent parameter actually represents.

What is unclear

• Is :agent the YAML filename (without .yaml extension)?
• Is it a field defined inside the YAML config itself?
• Is it always root, or something else?

What I discovered through trial and error

The :agent parameter is the config filename without the .yaml extension, matching the file passed to docker agent serve api. For example:

# Start the server with this config file:
docker agent serve api config.01.golang.expert.yaml

# The correct agent identifier in the URL is:
POST /api/sessions/:id/agent/config.01.golang.expert

Using root or any other value results in the request failing silently or returning unexpected behavior.

Additionally

The difference between the two endpoint variants is not explained:

POST /api/sessions/:id/agent/:agent         # When to use?
POST /api/sessions/:id/agent/:agent/:name   # When to use?

It is unclear when to use :name and what it refers to (a sub-agent name defined in the YAML?).

Suggested fix

1. Explicitly document that :agent is the config filename without the .yaml extension.
2. Add a concrete example with a real filename (not a placeholder).
3. Explain the difference between the two endpoint variants and when each should be used, with an example showing how to target a specific sub-agent (e.g., coder or reviewer in a multi-agent config).

[devguoo]

I dug through the server code a bit, and the issue description looks correct.

What the implementation does today is roughly:

• :agent is looked up as the API agent/config identifier (sm.Sources[agentFilename])
• for local file sources, that identifier is typically the config filename without .yaml / .yml
• if :name is omitted, the server defaults to root
• if :name is present, it targets a specific named agent from that config/team

So in practice, a docs note like this would probably remove most of the ambiguity:

:agent is the agent/config identifier exposed by GET /api/agents. When the API server is started from a local file such as config.01.golang.expert.yaml, that identifier is typically config.01.golang.expert.

POST /api/sessions/:id/agent/:agent runs the config's root agent.

POST /api/sessions/:id/agent/:agent/:name runs a specific named agent from that same config, where :name is the agent key from the YAML (for example coder, reviewer, etc.).

Small nuance: describing :agent as only “filename without extension” may be a bit too narrow, because the more general concept seems to be the API agent id; the filename rule is just the common local-file case.

[dgageot]

@devguoo would you like to open a PR?