Agent Response Schema#

Overview#

The Agent API exposes roster agents and invite-options through two distinct response paths that differ in base class, serialization method, and icon handling. Understanding these differences is critical when consuming or extending agent endpoints.

Response Model Hierarchy#

There are two parallel response shapes for roster agents:

1. Pydantic ResponseModel-based — used by the dedicated /agent/roster and /agent/invite-options endpoints (registered at GET /agent/roster and GET /agent/invite-options in roster.py).

• AgentRosterResponse in api/fields/agent_fields.py holds the core agent fields: icon_type, icon, icon_background, and metadata. It extends ResponseModel from api/fields/base.py, which sets from_attributes=True, extra="ignore", and serialize_by_alias=True.
• AgentInviteOptionResponse extends AgentRosterResponse with three extra fields: is_in_current_workflow, in_current_workflow_count, and existing_node_ids.
• Neither model defines an icon_url computed field. Consumers receive raw icon and icon_type values — no URL conversion is performed.

2. AppDetailWithSite/AppPartial-based — used by the generic /agent (Agent App) endpoints that remap an App ORM object to a roster-shaped response.

• AppPartial and AppDetailWithSite in api/controllers/console/app/app.py both carry a @computed_field property icon_url that calls build_icon_url(icon_type, icon).
• AppDetailSiteResponse, embedded in AppDetailWithSite as the site field, also computes icon_url for the WebApp site surface 1.

icon_url Availability by Endpoint#

build_icon_url returns None for non-image icon types (e.g., emoji), and a signed file URL for image type 2.

Serialization Path Differences#

Roster / Invite-options endpoints use AgentRosterService.serialize_agent(), a static method that manually builds a plain dict 3. This dict is then validated and serialized via dump_response(AgentRosterListResponse, ...) or dump_response(AgentInviteOptionsResponse, ...). The service populates icon directly from the Agent ORM field without conversion 4.

Agent App endpoints use Pydantic's model_validate(..., from_attributes=True) against AppDetailWithSite or AgentAppPagination, which triggers the icon_url computed field during serialization 5.

The roster and invite-options responses are built from the Agent model directly, while Agent App responses are built from the App model re-shaped by _serialize_agent_app_detail / _serialize_agent_app_pagination .

AgentComposerAgentResponse — Composer surface#

The Composer surface uses AgentComposerAgentResponse (also a ResponseModel), which mirrors the roster shape with icon_type, icon, icon_background but no icon_url. It also uses str | None for icon_type instead of the typed AgentIconType enum.

Key Source Files#