Embed an Agent
You normally reach an Agentix agent by opening the chat page and talking to it yourself. Embedding an agent means letting your own code talk to it instead of a person: a CI job, a batch script, another C3 application, or a UI you build yourself. The chat page is for people. Embedding is for everything else, putting that same agent behind a surface you control or driving it programmatically with no UI at all.
Two ways to embed an agent
Match what you're building to the row that fits:
| If you want to... | Use... | Because... |
|---|---|---|
| Add a chat surface that looks and behaves like the Agentix chat page, inside a C3 app on the same cluster | The drop-in NexusChatEmbed component. See Embed a chat in a C3 app. | It needs no server-side integration: no proxy, no OAuth client, no token to manage, because every call runs under the host app's own sign-in. |
| Drive an agent from your own code — a script, a job, another service, or a custom UI — on any cluster, with any caller | The Agent REST API — the rest of this page. | You need full programmatic control over sessions, messages, and files, and your caller may not be a browser inside a C3 app at all. |
If you're building a same-cluster, in-app chat page and don't need anything beyond the standard chat experience, use the drop-in embed instead of the REST API — see Embed a chat in a C3 app. The rest of this section covers the second path: driving an agent yourself over HTTP.
What the Agent REST API lets you do
The Agent REST API exposes everything the chat page does — starting a conversation, sending a prompt, following the agent's tool calls as they happen, and reading and writing files in its workspace — as a versioned HTTP surface (/agent-api/v1/) that any caller can drive. That opens the same agent to callers the chat page cannot serve:
- CI and batch jobs that need to run an agent as a step in a pipeline, and read its transcript to know how the run went, with no person there to click approve.
- Other C3 applications, including ones outside your cluster, that want to build their own experience around an agent instead of sending users to Agentix's own chat page.
- Custom UIs and tools, where you want to control the presentation yourself but still want the agent's tool execution, streaming replies, and file exchange underneath.
Whatever your caller is, it's talking to a session: the same unit of state as a chat conversation started from the chat page, with its own transcript, its own workspace, and its own agent-service pod — the isolated container that runs the agent for that session — behind it. From your code's point of view, a session moves through the same lifecycle as a human's chat — create, ready, active, stopped, deleted — except every step happens as an HTTP call you make, not a click.
Control plane and data plane
Your integration talks to two different endpoints, and telling them apart is most of the work:
- The control plane, on the C3 AI Agentix app itself, handles low-volume lifecycle and discovery: creating, listing, and stopping a session, and looking up which agents and models are available.
- The data plane, on the per-session agent pod the control plane hands you back, carries the high-volume traffic: every message, the event stream of the agent's reply, and file uploads and downloads.
Authentication
Every Agent REST API caller is gated by the same Agentix.User role a human needs to chat, but how you get a credential depends on where your caller runs:
- Same environment as Agentix, when your integration's own code is a C3 application there: mint the platform's own session token and present it — no OAuth, nothing to register.
client_credentials, for a headless caller with no human behind it — a CI job, a batch script, a service.authorization_codewith PKCE, for a caller in a different environment that should act as a specific signed-in person, so its permissions and session history are theirs, not a shared service account's.
The two OAuth paths start with a one-time step that an app administrator does before any code runs: registering an OAuth application on your Agentix environment. All three paths are covered in full, with runnable examples, in Using the Agentix REST API.
Where to go from here
Two more pages cover the API, and they answer different questions:
- Using the Agentix REST API is a task guide. Follow it the first time you build an integration: authenticate, and run one complete session end to end — create it, wait for it to be ready, send a message, read the streamed reply, exchange files, and clean up — plus a troubleshooting table for when a call fails.
- Agentix REST API Reference is the reference you keep open while you build. It's the endpoint-by-endpoint reference: every request and response shape, and the behaviors that don't show up in a single walkthrough but matter once your integration is live — idempotency, streaming semantics, rate limits, and the full, live
openapi.jsoncontract you can load into Swagger UI or generate a client from. - Quick Start is the human-facing conversation surface that the Agent REST API mirrors programmatically. Compare the two if you want to see how a session behaves before you build against it.