Ship an agent integration without guessing.

Five-minute quickstart

Call your published agent

1. 1
   Release a tested draft

   In the studio, complete Setup, add trusted knowledge, pass evaluations, and publish to staging. The first release initializes production; later versions need owner promotion.

2. 2
   Create an agent API key

   Open Release & API, create a key, and copy it immediately. Only its hash is stored.

3. 3
   Send the first message

   Use a unique idempotency key for each logical request. Save the returned conversationId.

curl -X POST "https://YOUR_HOST/v1/agents/AGENT_ID/responses" \
  -H "Authorization: Bearer gqa_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: visitor-42-message-1" \
  -d '{"input":"Which plan is right for a small team?","externalUserId":"visitor-42"}'

const response = await fetch(
  "https://YOUR_HOST/v1/agents/AGENT_ID/responses",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AGENTGROUND_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "visitor-42-message-1"
    },
    body: JSON.stringify({
      input: "Which plan is right for a small team?",
      externalUserId: "visitor-42"
    })
  }
);
if (!response.ok) throw new Error(await response.text());
const result = await response.json();

import os
import requests

response = requests.post(
    "https://YOUR_HOST/v1/agents/AGENT_ID/responses",
    headers={
        "Authorization": f"Bearer {os.environ['AGENTGROUND_API_KEY']}",
        "Idempotency-Key": "visitor-42-message-1",
    },
    json={
        "input": "Which plan is right for a small team?",
        "externalUserId": "visitor-42",
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()

For later turns, send the returned conversationId with only the newest user message. Production conversations stay pinned to the version on which they began.

Embed in another app

Send and receive messages from your own product

One agent API key is everything an external application needs. Discover the agent instead of hard-coding identifiers, keep a conversationId next to your own user record, and set externalUserId so conversations, leads, and handoffs stay attributable to the right person in your system.

# 1. Discover the agent behind this key
curl "https://YOUR_HOST/v1/agent" -H "Authorization: Bearer gqa_YOUR_AGENT_KEY"

# 2. Open a conversation for one of your users
curl -X POST "https://YOUR_HOST/v1/conversations" \
  -H "Authorization: Bearer gqa_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId":"crm-user-8814","title":"Refund for order 4182","metadata":{"tenant":"acme"}}'

# 3. Send each new user message on that conversation
curl -X POST "https://YOUR_HOST/v1/agents/AGENT_ID/responses" \
  -H "Authorization: Bearer gqa_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: helpdesk-msg-99213" \
  -d '{"input":"My refund has not arrived yet.","conversationId":"sess_…","externalUserId":"crm-user-8814"}'

The full walkthrough — a Node.js client, error table, and production checklist you can hand to another team — ships with the repository as docs/integration-guide.md.

Agent-led conversations

Let the agent open, ask, and gather

Most agents wait to be asked. An agent-led agent does the opposite: it speaks first, keeps the initiative, and works through an agenda — qualifying, promoting, and collecting information while the person simply replies. The Product promoter, Appointment booker, Feedback collector, Event registration, Renewal concierge, and Onboarding guide presets all use it.

# Open the conversation and render what the agent says first
curl -X POST "https://YOUR_HOST/v1/conversations" \
  -H "Authorization: Bearer gqa_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId":"visitor-42"}'

{
  "conversation": { "id": "sess_…", "messageCount": 1 },
  "conversationStyle": "agent_led",
  "openingMessage": "Hi! I'm here to help you find the right fit… what are you hoping to use it for?",
  "output": [{ "id": "msg_…", "role": "assistant", "content": "Hi! I'm here to help you find the right fit… " }]
}

# The person replies; you keep sending only their new message
curl -X POST "https://YOUR_HOST/v1/agents/AGENT_ID/responses" \
  -H "Authorization: Bearer gqa_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Mostly for work — I edit video.","conversationId":"sess_…"}'

If you skip POST /v1/conversations and send a message straight away, the opener is still seeded as the first turn — you just will not have had a chance to display it. For agent-led agents, open the conversation first.

Webhook events

Receive agent activity without polling

A project owner registers one allow-listed HTTPS destination per agent and subscribes it to the events the integration needs. Every delivery is signed, retried with backoff, and identified by a stable delivery ID.

{
  "id": "evt_01JABC",
  "type": "message.created",
  "createdAt": "2026-08-08T10:31:02.441Z",
  "data": {
    "conversationId": "sess_…",
    "agentId": "agt_…",
    "channel": "api",
    "externalUserId": "crm-user-8814",
    "message": { "id": "msg_…", "role": "assistant", "content": "…", "citations": [] }
  }
}

Existing endpoints keep their handoff-only subscription until an owner changes it, so enabling message events is always an explicit decision. Verify AgentGround-Signature and deduplicate on AgentGround-Delivery exactly as shown under Handoffs and webhooks.

Authentication

Use the narrowest credential

Requests and retries

Make production calls safely

Streaming

Receive an ordered response lifecycle

Set stream: true to receive Server-Sent Events. Each JSON data object has a monotonic sequence. The current implementation reports lifecycle progress and emits the complete answer in response.output_text.done; it does not claim token-by-token output.

curl -N "https://YOUR_HOST/v1/agents/AGENT_ID/responses" \
  -H "Authorization: Bearer gqa_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: visitor-42-message-2" \
  -d '{"input":"Compare the plans","conversationId":"sess_…","stream":true}'

Knowledge grounding

Show which approved excerpts supported an answer

AgentGround splits saved knowledge into overlapping excerpts, ranks them against the newest visitor question, and sends only the most relevant bounded set to the model. When the answer uses a supplied marker such as [S1], the response stores and returns that exact source snapshot.

{
  "role": "assistant",
  "content": "Returns are accepted within 30 days [S1].",
  "citations": [{
    "marker": "S1",
    "sourceId": "knw_…",
    "title": "Returns policy",
    "excerpt": "Unused purchases may be returned within 30 days."
  }]
}

Website widget

Embed chat without exposing your agent key

Your backend authenticates the visitor as appropriate, calls the widget-session endpoint with its server-side gqa_ key, and returns the short-lived response. The page loads /widget.js and points it at that backend endpoint. The resulting client secret is pinned to one published version and exact browser origin. A stable externalUserId also lets a refreshed session resume only that visitor's conversation; anonymous sessions restart when their client secret expires.

1. Create the customer-backend endpoint

// This code runs on your server. AGENTGROUND_API_KEY never reaches the browser.
const session = await fetch(
  "https://YOUR_HOST/v1/agents/AGENT_ID/widget-sessions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AGENTGROUND_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      allowedOrigin: "https://www.example.com",
      externalUserId: authenticatedCustomer.id
    })
  }
);
return Response.json(await session.json(), { status: session.status });

2. Add the widget to the website

<script
  src="https://YOUR_HOST/widget.js"
  data-token-endpoint="/api/agent-widget-session"
  data-title="Ask our product guide"
  data-greeting="Hello! What would you like to know?"
  data-color="#183c2f"
  async></script>

Core concept

Draft privately, publish deliberately

Management endpoints edit the mutable draft. Publishing snapshots its model, prompt, knowledge, connectors, and lead schema into staging. The first release initializes production; later production changes require an owner promotion. Existing conversations remain on their starting version.

Human escalation

Turn an agent escalation into durable work

Enable Human handoff on the draft and describe when escalation is appropriate. The agent can then create one active ticket per conversation with a reason, factual summary, priority, stable ID, and lifecycle status. Publishing freezes those rules for new production sessions; your team can still move tickets through open, in_progress, resolved, and closed.

Verify the raw request body before parsing JSON

import { createHmac, timingSafeEqual } from "node:crypto";

const rawBody = await readRawRequestBody(request);
const parts = Object.fromEntries(
  request.headers["agentground-signature"].split(",").map(part => part.split("=", 2))
);
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
const expected = createHmac("sha256", process.env.AGENTGROUND_WEBHOOK_SECRET)
  .update(`${parts.t}.${rawBody}`)
  .digest("hex");
const valid = age <= 300 && expected.length === parts.v1.length &&
  timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
if (!valid) throw new Error("Invalid or stale AgentGround signature");

const event = JSON.parse(rawBody);
// Deduplicate by event.id / AgentGround-Delivery, then return 2xx quickly.

The signing secret is shown only when an endpoint is created or rotated. The signature format is t=UNIX_SECONDS,v1=HEX_HMAC over timestamp + "." + rawBody. Reject signatures older than five minutes, use a constant-time comparison, and keep clocks synchronized.

Teams and releases

Give people only the access their job needs

A project owner can add an existing AgentGround account as an editor or viewer. Editors can change drafts, test, run evaluations, and create immutable staging releases. Viewers can inspect the project without changing it. Only the owner can manage membership, production promotions, API keys, provider credentials, and webhook secrets.

Connection workflow

Enable reviewed capabilities without exposing configuration

GET /api/connectors returns the safe catalog installed by the operator: name, description, scope, approval policy, method, and destination host. Editors select connector names on the draft; the server validates every name and derives scopes rather than trusting browser-supplied permissions.

Evaluation suites

Gate publishing on repeatable checks

Create up to ten representative cases for an agent draft. Each case supplies a visitor message and one to eight required response keywords. Run the suite after every meaningful draft change; only results from the current draftRevision count toward readiness.

Evaluation inputs, model outputs, and case results are stored in SQLite and follow the configured conversation retention policy. Observability responses expose model, latency, status, request ID, and token counts without prompts or provider credentials.

Errors

One predictable error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable explanation.",
    "details": {},
    "requestId": "b4b34d3e-…"
  }
}

Reference

Choose the API surface for the job