Chat

Start a live text conversation with any agent from your terminal. Test multi-turn flows, verify tool calls, and validate agent behavior before deploying.

Commands

Command	Description
`chanl chat <agent-id>`	Start an interactive chat session
`chanl chat <agent-id> -m "..."`	Send a single message and exit

Interactive Mode

Start a conversation and type messages in real time. The agent responds after each turn.

chanl chat agent_abc123

Connected to: Customer Support Bot (agent_abc123)
Type messages below. Ctrl+C to end.
────────────────────────────────────────────────────

You: Hi, I need help with my account.

Agent: Hello! I'd be happy to help you with your account. Could you
       tell me what you need assistance with?

You: I want to update my billing address.

Agent: Sure, I can help with that. Could you provide me with your
       new billing address?

You: 123 Main St, Springfield, IL 62701

Agent: I've updated your billing address to 123 Main St, Springfield,
       IL 62701. You'll see the change reflected on your next invoice.
       Is there anything else I can help with?

You: No, that's all. Thanks!

Agent: You're welcome! Have a great day.

You: ^C
Session ended. ID: sess_xyz789

What to look for

Does the agent greet appropriately?
Does it use tools when expected (order lookups, knowledge search)?
Does it handle multi-turn context (remembering earlier messages)?
Does it stay on topic and follow the system prompt?

Single Message Mode

Send one message, get one response. No interactive session.

chanl chat agent_abc123 --message "What are your business hours?"

Agent: Our business hours are Monday through Friday, 9 AM to 6 PM
       Eastern Time. We're also available on Saturdays from 10 AM
       to 2 PM.

Useful for quick smoke tests and scripted checks.

Options

Option	Short	Description
`--message <text>`	`-m`	Send a single message (non-interactive)
`--session <id>`	`-s`	Resume an existing session
`--customer <id>`	`-c`	Attach a customer record (enables memory)
`--json`	`-j`	Output response as JSON
`--workspace <id>`	`-w`	Override default workspace

JSON Output

Get structured output for scripting and assertions:

chanl chat agent_abc123 --message "What is your return policy?" --json

{
  "sessionId": "sess_xyz789",
  "interactionId": "int_abc123",
  "agentId": "agent_abc123",
  "message": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging. Would you like to start a return?",
  "toolCalls": [
    {
      "tool": "kb_search",
      "args": { "query": "return policy" },
      "result": "Returns accepted within 30 days..."
    }
  ]
}

Testing Patterns

Smoke test an agent

chanl chat agent_abc123 -m "Hello" --json | jq -r '.message'

Test tool usage

chanl chat agent_abc123 -m "Look up order ORDER-12345" --json | \
  jq '.toolCalls'

[
  {
    "tool": "lookup_order",
    "args": { "orderId": "ORDER-12345" },
    "result": { "status": "shipped", "tracking": "1Z999..." }
  }
]

Test with customer memory

Attach a customer record so the agent has memory context:

chanl chat agent_abc123 --customer cust_abc123

Connected to: Customer Support Bot (agent_abc123)
Customer: Maria Chen (cust_abc123)
────────────────────────────────────────────────────

You: What's the status of my order?

Agent: Hi Maria! I can see your recent order ORDER-55821 shipped
       yesterday. The tracking number is 1Z999AA10123456784.
       Would you like me to send you the tracking link?

Script multiple test messages

messages=(
  "Hello, I need help"
  "I want to cancel my subscription"
  "My account ID is ACC-12345"
  "Yes, please proceed with cancellation"
)

for msg in "${messages[@]}"; do
  echo "You: $msg"
  chanl chat agent_abc123 -m "$msg" --json | jq -r '"Agent: " + .message'
  echo ""
done

CI assertion

response=$(chanl chat agent_abc123 -m "What is your return policy?" --json)

# Check the agent used knowledge base
tool_used=$(echo "$response" | jq -r '.toolCalls[]?.tool' | grep -c "kb_search")
if [ "$tool_used" -eq 0 ]; then
  echo "FAIL: Agent did not search knowledge base"
  exit 1
fi

echo "PASS: Agent used kb_search"

Help

chanl chat --help

Usage: chanl chat [options] <agent-id>

Start a text chat session with an AI agent

Arguments:
  agent-id                The agent to chat with

Options:
  -m, --message <text>    Send a single message (non-interactive)
  -s, --session <id>      Resume an existing session
  -c, --customer <id>     Attach a customer record
  -j, --json              Output as JSON
  -w, --workspace <id>    Override default workspace
  -h, --help              Display help for command

SDK: Chat Module

Build chat into your application with the SDK

Platform: Scenarios

Automated agent testing with personas and scorecards

Tools & Toolsets

Create the tools your agents use during chat

Knowledge Base

Add knowledge so agents can answer questions

SDK: Chat Module

Platform: Scenarios

Tools & Toolsets

Knowledge Base

On this page