Skip to main content
POST
/
v1
/
sessions
/
{session_id}
/
message
Send Message
curl --request POST \
  --url https://api.example.com/v1/sessions/{session_id}/message \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "start_url": "<string>"
}
'
{
  "success": true,
  "message": "Message sent successfully"
}

​
Overview

Send a user message to the agent. Use this to:
  • Start a new task - Give the agent initial instructions
  • Answer questions - Respond when the agent asks for clarification
  • Provide updates - Give the agent new information mid-task

​
Request

​
session_id
string
required
The UUID of the session
​
Authorization
string
required
Bearer token for authentication
​
message
string
required
The message text to send to the agent (1-10,000 characters)
​
start_url
string
Optional starting URL for the agent to navigate to (max 2,000 characters)

​
Response

​
success
boolean
required
Whether the message was successfully queued
​
message
string
required
Confirmation message
{
  "success": true,
  "message": "Message sent successfully"
}

​
Example Requests

import { AGIClient } from 'agi';

const client = new AGIClient({ apiKey: 'your_api_key' });

// Send message (basic)
await client.sendMessage(sessionId, 'Find three nonstop SFO→JFK flights next month under $450');

// Send message with start URL
await client.sendMessage(sessionId, 'Compare prices for iPhone 15', {
  start_url: 'https://www.apple.com'
});

// Answer a follow-up question
await client.sendMessage(sessionId, 'Yes, include startups founded after 2020');

​
Validation

Messages are validated for:
  • Non-empty text
  • Length ≤ 10,000 characters
  • Valid UTF-8 encoding

​
Use Cases

​
E-commerce Research

{
  "message": "Find the cheapest price for Sony WH-1000XM5 headphones on major retailers",
  "start_url": "https://www.google.com"
}

​
Form Filling

{
  "message": "Fill out this job application with my resume information",
  "start_url": "https://company.com/careers/apply"
}

​
Data Extraction

{
  "message": "Extract all product names and prices from this page into a structured format",
  "start_url": "https://example.com/products"
}

​
Flight Booking

{
  "message": "Book a round-trip flight from SFO to NYC, departing June 15, returning June 22, economy class, prefer morning flights"
}

​
Responding to Questions

When the agent asks a question (message type QUESTION), respond naturally: 
{
  "message": "Yes, evening flights between 6-9 PM are preferred"
}

​
Message Patterns

​
Clear Task Definition

✅ Good: “Find 3 nonstop flights from SFO to JFK on June 15, budget $400-500, prefer morning departures” ❌ Bad: “Find flights”

​
Structured Requests

✅ Good: “Research iPhone 15 pricing at Best Buy, Amazon, and Apple Store. Return as JSON with store name and price” ❌ Bad: “Check iPhone prices”

​
Actionable Instructions

✅ Good: “Navigate to LinkedIn, search for ‘machine learning engineers in San Francisco’, and save the first 10 profiles” ❌ Bad: “Find some ML engineers”

​
Best Practices

Be specific in your instructions. Include:
  • What you want the agent to do
  • Any constraints (budget, time, preferences)
  • Expected output format
The agent will ask questions if it needs clarification. Monitor messages and respond promptly.
Each session can only handle one task at a time. Wait for the current task to finish before starting a new one.