Xagent Docs
Get started

End-to-End Example

A complete run through the Workspace SDK: provision an agent, run a task, poll until it finishes, and read the result. Two keys are involved — a personal key (xag_personal_…) to create the agent, and the runtime key (xag_…) it mints to run tasks.

Base URL

Examples use https://your-domain.com. For a local install substitute http://localhost:8000. See API Reference for authentication and error details.

1. Provision an agent

Create the agent with your personal key, requesting a runtime key in the same call:

curl -X POST https://your-domain.com/v1/agents \
  -H "Authorization: Bearer xag_personal_Zx7Qw2_5Yh8Rk3Mn6Pd1Wf4Tg9Bv2Cs7Lj0Ae" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "instructions": "Produce concise, sourced competitor reports.",
    "tool_categories": ["basic"],
    "generate_runtime_key": true
  }'

Response (200): keep agent.id and api_key.full_key — the full key is shown only once.

{
  "agent": { "id": 42, "name": "Research Assistant", "status": "active" },
  "api_key": {
    "full_key": "xag_Ab3xY9_Qw7Rt2Kp9Lm4Nz8Vc1Bd6Hf5Jg0Xs3Tr",
    "key_prefix": "Ab3xY9",
    "created_at": "2026-06-23T12:00:00Z"
  }
}

2. Create a task

Switch to the runtime key and send the first message. The response is 202 Accepted with the new task_id:

curl -X POST https://your-domain.com/v1/chat/tasks \
  -H "Authorization: Bearer xag_Ab3xY9_Qw7Rt2Kp9Lm4Nz8Vc1Bd6Hf5Jg0Xs3Tr" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 42, "message": {"role": "user", "content": "Summarize the EV battery market."}}' 
{
  "task_id": 101,
  "agent_id": 42,
  "status": "running",
  "created_at": "2026-06-23T12:00:00Z",
  "run_id": "run_9f2c1a",
  "state_version": 1,
  "control_state": "running"
}

3. Poll for completion

Poll the task with the runtime key until status is completed (or failed). For a live progress timeline, poll /steps alongside it.

curl https://your-domain.com/v1/chat/tasks/101 \
  -H "Authorization: Bearer xag_Ab3xY9_Qw7Rt2Kp9Lm4Nz8Vc1Bd6Hf5Jg0Xs3Tr" 
{
  "task_id": 101,
  "agent_id": 42,
  "workforce_id": null,
  "status": "running",
  "run_id": "run_9f2c1a",
  "state_version": 2,
  "control_state": "running",
  "input": "Summarize the EV battery market.",
  "output": null,
  "error": null,
  "created_at": "2026-06-23T12:00:00Z",
  "completed_at": null
}

4. Read the output

Once status is completed, the answer is in output:

{
  "task_id": 101,
  "agent_id": 42,
  "workforce_id": null,
  "status": "completed",
  "run_id": "run_9f2c1a",
  "state_version": 4,
  "control_state": "completed",
  "input": "Summarize the EV battery market.",
  "output": "The EV battery market is projected to...",
  "error": null,
  "created_at": "2026-06-23T12:00:00Z",
  "completed_at": "2026-06-23T12:00:47Z"
}

Continue the conversation

To ask a follow-up, append another message with POST /v1/chat/tasks/101/messages. If the task is still running you get 409 task_busy — poll until it completes, then append.

Next Steps