​

SDK & API Keys

​

/api/* vs /v1/*

• You are acting as an authenticated owner in the web app model
• You manage agents, workforces, or knowledge with JWT-based auth

• You want a stable programmatic integration surface
• You are calling Xagent from your own backend or application
• You want API-key-based access instead of browser session auth

​

Two key types

​

Personal keys

• Developer tooling
• Personal automation
• Service-to-service access tied to a user identity

​

Agent runtime keys

​

Common SDK flow

1. Create or choose an agent
2. Generate the agent runtime key
3. Call POST /v1/chat/tasks
4. Poll GET /v1/chat/tasks/{task_id}
5. Fetch steps or append messages as needed

​

Dispatch class and priority

• dispatch_class: interactive or batch. Omit it or send null to let the server decide.
• priority: an integer from -10 to 10. Omit it or send null for 0. A value out of range, a boolean, a float, or a number sent as a string is rejected with 422.

​

When the server uses them

• The task must run through the dispatch queue (shared task execution, XAGENT_SHARED_TASK_EXECUTION_ENABLED). Otherwise the fields are stored but have no scheduling effect.
• With the default classification, a requested class is adopted only when both XAGENT_DISPATCHER_FAIR_SHARE and XAGENT_DISPATCH_ACCEPT_REQUESTED_CLASS are on. Both are off by default. Otherwise the class follows the task source, which is batch for SDK tasks.
• With the default classification, an answer to a waiting task is always interactive.
• The class is decided when each command is enqueued, so changing these settings affects only commands enqueued afterwards.
• Priority is applied when commands are dispatched. It has an effect only when fair share is on. It orders commands of the same account and the same class, also when that account is the only one with queued commands, and never lets one account jump ahead of another. Some dispatch rounds still pick the oldest command first.
• A deployment can install its own classification rule, which may also set its own priority. In that case, trust the dispatch_class in the response.

​

Checking the result

from xagent_sdk import AgentClient

client = AgentClient()  # reads XAGENT_API_KEY and XAGENT_BASE_URL
result = client.tasks.create(
    agent_id=agent_id,
    message="Summarize the open tickets.",
    dispatch_class="interactive",
    priority=5,
)
print(result.dispatch_class)  # "interactive" if adopted; "batch" or None otherwise

​

Related endpoints

• Personal keys: API Reference
• Agent runtime key: API Reference
• SDK tasks: API Reference
• SDK task status: API Reference
• Append message to task: API Reference

​

When to document more

• Request examples
• Retry strategy
• Error handling conventions
• Key rotation policy