Getting Started with Agent700.ai

This page will help you get started with Agent700.ai. You’ll be up and running in a jiffy!

What is Agent700?

Agent700 is an enterprise-grade AI Agent Management Platform that lets you create, manage, and deploy AI agents across multiple LLM providers with strong security, real-time streaming, and MCP tool integrations.

Key Capabilities

AI Agent Management with revisions
Real-time streaming via WebSockets
MCP (Model Context Protocol) tools & resources
JWT auth with refresh rotation & device fingerprinting
Org-aware access, billing, and audit logging
Document processing & alignment data storage

Prerequisites

Agent700 API base URLs:
- Production: https://api.agent700.ai
An Agent700 account and organization membership
A REST client (cURL, Postman, etc.)
(Optional) Import the OpenAPI spec into Postman/Swagger UI

Common Headers

Header	Type	Required	Description
Authorization	string (Bearer)	Yes	JWT access token or App Password token (`app_a7_...`)
X-Organization-ID	string (uuid)	Often	Active organization context for org-aware endpoints
Content-Type	string	When body	`application/json`

Replace this screenshot with your Agent700 dashboard image.

1) Authenticate

Authenticate with email/password and receive a JWT access token. Device fingerprinting headers can enhance security.

curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -H "X-Screen-Resolution: 1920x1080" \
  -H "X-Timezone-Offset: -300" \
  -d '{
    "email": "[email protected]",
    "password": "yourPassword"
  }'

Keep the httpOnly refresh token (cookie) the server returns. To refresh:

curl -X POST "$BASE_URL/api/auth/refresh" \
  -H "Cookie: refreshToken=YOUR_REFRESH_COOKIE" \
  -H "X-Screen-Resolution: 1920x1080" \
  -H "X-Timezone-Offset: -300"

2) Set Organization Context

Pass your organization via header:

-H "X-Organization-ID: 11111111-2222-3333-4444-555555555555"

3) Create Your First Agent

curl -X POST "$BASE_URL/api/agents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "masterPrompt": "You are a helpful assistant.",
    "introductoryText": "Hello! How can I help you?",
    "model": "gpt-4",
    "streamResponses": true,
    "enableMcp": false
  }'

List accessible agents:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "X-Organization-ID: $ORG_ID" \
     "$BASE_URL/api/agents"

4) Send Your First Chat

Standard (non-streaming)

curl -X POST "$BASE_URL/api/chat" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_UUID",
    "messages": [
      {"role": "user", "content": "Hello Agent700!"}
    ],
    "streamResponses": false
  }'

SSE Streaming

curl -N -X POST "$BASE_URL/api/chat/stream" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_UUID",
    "messages": [
      {"role": "user", "content": "Stream a response please"}
    ],
    "streamResponses": true
  }'

Expect events like chat_message_response, mcp_tool_complete_in_content, mcp_tool_message, heartbeat, and stream_complete.

SSE event shape

When an agent uses MCP tools during streaming, the SSE stream can include content chunks, tool call markers, tool results, keepalive events, and a final completion event.

event: chat_message_response
data: {"content": "\n\n<tool_use>\n<name>use_mcp_tool</name>\n<server_name>brave-search</server_name>\n<tool_name>brave_web_search</tool_name>\n<arguments>\n{\n  \"query\": \"Buffalo Sabres first playoff game 2024 date\",\n  \"count\": 10\n}\n</arguments>\n</tool_use>", "stream_id": "sse_ab64706b-be31-46b6-a6d5-4295912baa39_1775592516", "timestamp": 1775592517.7979128}

event: chat_message_response
data: {"finish_reason": "tool_calls", "safety_ratings": null, "stream_id": "sse_ab64706b-be31-46b6-a6d5-4295912baa39_1775592516", "timestamp": 1775592518.1880374}

event: mcp_tool_complete_in_content
data: {"stream_id": "sse_ab64706b-be31-46b6-a6d5-4295912baa39_1775592516", "tool_use_block": "<tool_use>\n<name>use_mcp_tool</name>\n<server_name>TimeDate</server_name>\n<tool_name>current_time</tool_name>\n<arguments>\n{\n  \"timezone\": \"America/New_York\"\n}\n</arguments>\n</tool_use>", "result_block": "\n\nTool Result:\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"Current time in America/New_York: 4/7/2026, 4:08:38 PM\"\n    }\n  ],\n  \"isError\": false\n}\n```\n\n", "timestamp": 1775592520.5025692}

event: mcp_tool_message
data: {"stream_id": "sse_ab64706b-be31-46b6-a6d5-4295912baa39_1775592516", "message": {"role": "tool", "content": "{\"content\": [{\"type\": \"text\", \"text\": \"Current time in America/New_York: 4/7/2026, 4:08:38 PM\"}], \"isError\": false}", "tool_call_id": "call_1775592520_TimeDate_current_tim"}, "timestamp": 1775592520.5025854}

event: heartbeat
data: {"timestamp": 1775592546.3395183, "uptime": 30.198236227035522}

event: chat_message_response
data: {"content": "**", "stream_id": "sse_ab64706b-be31-46b6-a6d5-4295912baa39_1775592516", "timestamp": 1775592652.2770185}

event: chat_message_response
data: {"finish_reason": "stop", "safety_ratings": null, "stream_id": "sse_ab64706b-be31-46b6-a6d5-4295912baa39_1775592516", "timestamp": 1775592654.609329}

event: stream_complete
data: {"duration": 138.97093772888184}

Handle the stream as follows:

Use stream_id to correlate all events for the same request
Treat chat_message_response events with content as incremental output chunks
Treat finish_reason: "tool_calls" as a signal that the model requested tool execution before continuing
Read mcp_tool_complete_in_content to capture the rendered tool call and tool result together
Parse mcp_tool_message.message.content as a JSON string if you need structured tool output
Handle tool failures explicitly: in this stream, some mcp_tool_complete_in_content events returned "isError": true

SSE Health:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     "$BASE_URL/api/chat/stream/health"

4.5) JSON Structured Output

Enable JSON Structured Output on Agent700 agents to force responses into a predefined JSON schema, ensuring consistent, parseable output for API integrations.

Enable JSON Structured Output

When creating or updating an agent, include jsonOutputEnabled: true and a valid jsonSchema string.

Create Agent (POST)

curl -X POST "$BASE_URL/api/agents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "'"$ORG_ID"'",
    "name": "Customer Support Agent",
    "model": "claude-sonnet-4-5-20250929",
    "masterPrompt": "You are a helpful customer support agent.",
    "jsonOutputEnabled": true,
    "jsonSchema": "{\"type\":\"object\",\"properties\":{\"response\":{\"type\":\"string\",\"description\":\"The main response text\"},\"status\":{\"type\":\"string\",\"enum\":[\"success\",\"error\"],\"description\":\"Response status\"},\"ticketId\":{\"type\":\"integer\",\"description\":\"Support ticket ID\"}},\"required\":[\"response\",\"status\"],\"additionalProperties\":false}"
  }'

Note: organizationId is required in the request body. Do not use X-Organization-ID header.

Update Existing Agent

curl -X PUT "$BASE_URL/api/agents/$AGENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "'"$ORG_ID"'",
    "name": "Customer Support Agent",
    "model": "claude-sonnet-4-5-20250929",
    "jsonOutputEnabled": true,
    "jsonSchema": "{\"type\":\"object\",\"properties\":{\"response\":{\"type\":\"string\"},\"status\":{\"type\":\"string\",\"enum\":[\"success\",\"error\"]}},\"required\":[\"response\",\"status\"],\"additionalProperties\":false}"
  }'

Note: organizationId is required for PUT. Include name and model to avoid unintended changes.

Disable JSON Structured Output

curl -X PUT "$BASE_URL/api/agents/$AGENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "'"$ORG_ID"'",
    "name": "Customer Support Agent",
    "jsonOutputEnabled": false,
    "jsonSchema": null
  }'

Example Schemas

Basic Schema

{
  "type": "object",
  "properties": {
    "response": {
      "type": "string",
      "description": "The main response text"
    },
    "status": {
      "type": "string",
      "enum": ["success", "error"],
      "description": "Response status"
    }
  },
  "required": ["response", "status"],
  "additionalProperties": false
}

Complex Schema with Arrays

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "tags": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["id", "name"]
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "count": { "type": "integer" },
        "timestamp": { "type": "string", "format": "date-time" }
      }
    }
  },
  "required": ["data"],
  "additionalProperties": false
}

Common Schema Elements

Element	Description	Example
`type`	Data type	`"string"`, `"number"`, `"boolean"`, `"object"`, `"array"`
`properties`	Object property definitions	`{"name": {"type": "string"}}`
`required`	Required property names	`["response", "status"]`
`enum`	Allowed values	`["success", "error", "pending"]`
`description`	Property description	`"User's full name"`
`additionalProperties`	Allow extra properties	`false` for strict schemas
`items`	Array item schema	`{"type": "string"}`
`format`	Format specification	`"date-time"`, `"email"`, `"uri"`

Response Example

When JSON Structured Output is enabled, the agent's chat response will follow your schema:

{
  "error": null,
  "response": "{\"response\":\"Hello! I can help you with your account.\",\"status\":\"success\",\"ticketId\":12345}",
  "finish_reason": "stop",
  "scrubbed_message": "",
  "prompt_tokens": 25,
  "completion_tokens": 15
}

Validation Rules

jsonSchema must be valid JSON when jsonOutputEnabled is true
Schema must follow JSON Schema Draft 7 specification
Not available for image generation models (models starting with img)
The API validates schema format on create/update

Note: The jsonSchema field must be a JSON string, not a JSON object. If you have a JSON object, stringify it before sending to the API.

5) Integrate Tools with MCP (Optional)

List MCP servers (global):

curl "$BASE_URL/api/mcp/servers"

Agent-scoped examples require JWT, agent ownership, and MCP enabled on the agent.

Add a Server

curl -X POST "$BASE_URL/api/agents/$AGENT_ID/mcp/servers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather-server",
    "url": "https://api.weather.com/mcp",
    "transport_type": "http",
    "timeout": 30
  }'

Call a Tool

curl -X POST "$BASE_URL/api/agents/$AGENT_ID/mcp/tools/call" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "weather-server",
    "tool_name": "get_forecast",
    "arguments": {"city": "San Francisco", "days": 5}
  }'

Read a Resource

curl -X POST "$BASE_URL/api/agents/$AGENT_ID/mcp/resources/read" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "file-server",
    "uri": "file:///path/to/file.txt"
  }'

6) Alignment Data & App Passwords

Certain endpoints accept either JWT or an App Password (Bearer token starting with app_a7_...).

curl -X POST "$BASE_URL/api/alignment-data" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"global.setting.theme","value":"dark"}'

Fetch structured config from a pattern:

curl -H "Authorization: Bearer $TOKEN" \
     "$BASE_URL/api/alignment-data/by-pattern/global.*"

7) QA Sheets & Ratings (Optional)

Create a QA sheet:

curl -X POST "$BASE_URL/api/agents/$AGENT_ID/qa-sheets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"question": "What are your hours?", "answer": "Mon-Fri 9-5", "tags":["hours"]}
    ]
  }'

Submit a rating:

curl -X POST "$BASE_URL/api/ratings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_UUID",
    "agentRevisionId": 1,
    "messages": [
      {"role":"user","content":"Hi"},
      {"role":"assistant","content":"Hello!"}
    ],
    "rating": 5,
    "notes": "Great response quality"
  }'

8) Billing & Audit (Optional)

User billing:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     "$BASE_URL/api/billing/user?start_date=2025-10-01&end_date=2025-10-31"

Organization audit events (requires membership):

Submit:

curl -X POST "$BASE_URL/api/organizations/$ORG_ID/events" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events":[{"eventType":"USER_ACTION","severity":"INFO","details":{"clicked":"start"}}],
    "batchInfo":{"timestamp":"2025-10-02T12:00:00Z","clientId":"web-client-1"}
  }'

Query:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     "$BASE_URL/api/organizations/$ORG_ID/audit-events?hours=24&category=API&severity=INFO&limit=50"

Troubleshooting

401 Unauthorized

Check JWT or App Password token
Refresh the token if expired

403 Forbidden

Confirm your organization membership
Provide a valid X-Organization-ID header

SSE Issues

Verify Bearer token, CORS origin, and connection limits
Use the /api/chat/stream/health endpoint

MCP Errors

Confirm server configuration and connectivity
Check tool names and arguments

Support

Email: [email protected]
Docs: https://docs.agent700.ai
Tip: Import the OAS spec into your API tool for interactive testing