Chatting

How to interact with your agent.

In the workspace

1. Open your agent
2. Type a message
3. Watch it work

You'll see:

• The agent's thinking
• Tool calls as they happen
• Results as they come back

Example conversation

1You: Create a logo for "Morning Brew" coffee shop23Agent: I'd be happy to create a logo. A few questions:4       - What style? (minimal, vintage, modern)5       - Any specific colors?6       - Should I include a coffee cup icon?78You: Modern style, warm colors, yes include a cup910Agent: [Calling stable-diffusion...]11       12       Here's your logo! I created a modern design with 13       warm orange and brown tones featuring a stylized 14       coffee cup.15       16       Want me to create variations?

Widgets

Sometimes agents need structured input.

They can generate small UI forms:

1Agent: I need some details:23       ┌─────────────────────────┐4       │ Company: [____________] │5       │ Style: [Modern ▼]       │6       │ Colors: [____] [____]   │7       │                         │8       │ [Generate]              │9       └─────────────────────────┘

Fill it out and the agent continues.

From the terminal

After belt login, run agents and manage chats without opening the workspace:

1belt agent run myteam/my-agent "Hello"2belt agent run myteam/my-agent "Follow up" --chat chat_abc1233belt chat get chat_abc1234belt chat send chat_abc123 "What's the status?"   # streams the agent's reply5belt chat watch chat_abc123                       # re-attach without sending a new message

belt chat send streams the agent's response (same behavior as belt agent run). Use belt chat watch to follow a chat that is already running or after approving a tool without --watch.

When a tool requires approval, list and act on pending invocations:

1belt chat pending2belt chat approve ti_abc123 --watch

→ CLI setup · Agents API

Per-chat context

Agents that use call tools with {{context.X}} URL templates need context values when you start a chat. Declare fields in the agent config, then pass values at chat creation:

1{2  "agent_id": "agent_abc123",3  "context": {4    "project_id": "proj_456",5    "environment": "staging"6  }7}

Context is set once per chat and cannot change, so every tool call in that conversation uses the same project or environment.

→ Context in Adding Tools · Create Chat REST API

Structured results

When an agent uses the finish tool (required for structured output), the final JSON is stored on the chat as output. Retrieve it with GET /chats/:id (see Get Chat) or agent.run() in the SDK.

Inspecting execution

The workspace shows tool calls and reasoning as the agent runs. For integrations and debugging:

Use streaming when you need live updates; use List chat messages when you need a point-in-time transcript after the run. Use GET /chats/:id for chat-level metadata such as output and status.

Sending messages mid-run

While the agent is still working (chat.status is busy), you can send additional user messages without waiting for the current turn to finish. In the workspace, these appear as pending messages until the agent picks them up on its next turn.

Via REST, call POST /chats/:id/messages with a message string, or send another message with POST /agents/run / POST /agents/message using the same chat_id — when a run is already active, the API auto-queues instead of starting a new run. The message is created with status: "queued"; when the agent's next turn starts, it transitions to ready and is included in context. To withdraw a queued message before the agent consumes it, call POST /chats/messages/:messageId/cancel. See Send chat message, Cancel message, Queuing while a run is active, and Chat message status.

Terminal and API

• CLI — belt agent run, then belt chat get, pending, approve, or reject for follow-ups and human-in-the-loop. See CLI Setup.
• REST — New conversation: POST /chats (with agent) → POST /chats/:id/messages. One-shot: POST /agents/run. Follow-ups: GET /chats/:id (metadata), GET /chats/:id/messages (transcript), POST /chats/:id/messages, and POST /tools/:id/invoke or /reject. See Agents REST API.

Chat integrations

Connect your agent to external chat platforms. For Slack, configure your app's event subscription URL to the agent's channel webhook (POST /agents/{id}/channel/slack). See Messaging channel webhooks.

Talk to your workspace from where you already are. For custom HTTP tools mid-conversation, see Agent webhooks.

Tips

• Be specific about what you want
• Provide context when relevant
• Ask for variations if the first result isn't right

Next

→ Browsing the Grid