Skip to main content

Agents

The Agents section covers two routes that work together: the /agents grid where users pick an agent to talk to, and the /chat/:agentId (and /chat/:agentId/:threadId) view where the conversation happens. Both routes are accessible to all authenticated users; the Configure button on each card is visible to administrators only.

Agent Grid (/agents)​

The agents page opens with a page title Agents and a subtitle "Select an AI agent to start a conversation." A search bar filters the card list in real time by agent name. All filtering happens client-side — no additional API call is made while typing.

Each agent is rendered as a card containing the following information:

  • Agent icon — the agent's own icon: a custom image if one was uploaded, otherwise the icon chosen in Studio. When the agent has neither, it falls back to a glyph derived from agent_type and agent_arch, which visually distinguishes chat, task, and multi-agent architectures. See Agent Icon
  • Provider badge — indicates the backing LLM provider (e.g. OpenAI, Azure OpenAI, Anthropic)
  • Status badge — Active (green) when is_active is true, Draft (muted) otherwise
  • Agent name — displayed prominently; clicking anywhere on the card navigates to /chat/:agentId
  • Type badge — the agent_type value (e.g. chat, task)
  • Model badge — the first model name configured for the agent
  • Description — up to two lines of text; truncated with an ellipsis if longer
  • Configure button — visible to admins only; navigates to /configure/:agentId without navigating away from the grid when clicked (the click event is stopped from propagating to the card)
  • Locked badge — replaces the Configure button for suite-managed agents; indicates that orchestration is controlled by the installed suite and cannot be modified directly

Note: The grid queries airuntime/agent/ with type=assistant, published=true, and is_active=true. Agents that have not been published or have been deactivated in the agent builder do not appear here.

Chat View (/chat/:agentId)​

Clicking any agent card — or a Recent Agents row on the dashboard — opens the chat view. The page layout is split into two areas: the main chat area on the left and a right sidebar.

Main Chat Area​

The chat area fills the remaining width. Messages are displayed in a scrollable list. Human messages appear right-aligned; agent messages appear left-aligned. Tool calls made by the agent during a response are shown inline as ToolCallCard entries — each card is expandable and shows the tool name, input arguments, and output. Generative UI components (charts, data tables, KPI cards, maps, forms, approval actions, code blocks) are rendered inline within agent messages when the agent emits them.

When a response is streaming, a loading indicator is shown. Sending a message while a response is in flight is blocked until the stream completes. A Stop button is available during streaming to cancel the response. File attachments are supported for agents that have upload_files enabled; attached files are referenced in the message display by name.

If the thread is locked due to a content policy violation, the input area is replaced with a locked-conversation banner that shows the lock reason and instructs the user to start a new chat.

For passthrough agents that require Microsoft SSO, an AuthRequiredBanner is shown when the current session was not authenticated via Microsoft login, and the input is disabled until the user re-authenticates.

The right sidebar is fixed at 272 px wide and contains three regions:

Agent Summary — collapsible sections for the agent's Skills, Knowledge (datasources), and MCP Servers. Each section shows a count badge and, when expanded, pill badges listing the individual resource names. This panel is hidden for passthrough agents, which instead show the agent's description in an About block.

New Chat button — a primary New Chat button resets the in-memory conversation state and navigates to /chat/:agentId with a fresh chatKey. For passthrough agents, clicking New Chat also resets the remote CopilotKit session.

Recent Conversations — a scrollable list of previous threads for this agent, ordered by most recently updated. Clicking a thread item navigates to /chat/:agentId/:threadId, which loads the thread's message history from the backend and resumes the conversation. This panel is hidden for passthrough agents, which do not persist local thread history.

Thread Persistence​

After the agent's first reply in a new conversation, the runtime automatically creates a backend thread record. The thread name is derived from the first human message (up to 80 characters). The URL is silently updated to include the thread ID using window.history.replaceState — this avoids remounting the chat provider and losing in-memory messages while still making the URL bookmarkable.

Best Practices​

  • Use the search bar on the Agents grid to locate agents quickly in tenants with many deployed agents; the filter is instant and case-insensitive.
  • If an agent's tool calls appear in the message stream but the final answer is slow, the agent is waiting for a long-running external tool — check the underlying connection in Connections.
  • Open an existing thread from Recent Conversations instead of starting a new chat when continuing a multi-turn task; the agent has full access to the thread's message history.
  • Administrators should use the Configure button directly from the grid rather than navigating through the sidebar — it avoids an unnecessary page transition.
  • File uploads are only available for agents where upload_files is enabled in the agent builder; if the attachment button is not visible, the feature must be enabled in the agent's configuration.
  • Overview — runtime dashboard with recent activity and usage trends
  • Configure — per-agent skills, knowledge, MCP servers, channels, and notifications
  • Approvals — human-in-the-loop approval requests generated during agent runs
  • Notifications — notification feed for agent activity events
  • Connections — stored credentials bound to skills and datasources