Agents

An Agent is the reusable definition of an AI worker: its system prompt, the skills and knowledge it can use, the tools and connectors it’s allowed to call, which model handles which step, and its runtime policy. You configure an agent once and invoke it many times.

You don’t “call” an agent directly — you start a Run, referencing the agent by agentId:

curl https://api.nicia.ai/v1/runs \
  -H "x-api-key: $NICIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "<agent-id>", "input": { … } }'

Editing an agent while runs are open

An agent’s behavior is not pinned when a run starts. Every turn re-resolves the agent live — prompt, skills, model routing, and policies as they stand at that moment — so editing an agent does change runs already in flight, from their next turn onward. When a result has to be reproducible against a fixed configuration, finish the runs before you edit, or edit a copy.

A run does record a behaviorSnapshot, written once at its first turn. It is an audit record of what that turn resolved, and it answers “what did this run run with”. Nothing reads it back to decide what a later turn runs with.

POST /v1/runs accepts a pinnedVersions field and echoes it back on the run, but no execution path reads it. It pins nothing today — do not rely on it.

Input and output contracts

An agent may declare an inputSchema and an outputSchema. When an outputSchema is declared, a successful run’s output is a structured object validated against it. Agents without an outputSchema — the default — have no output field on the run at all: read the final assistant message instead, from GET /v1/runs/{runId}/messages or the stream’s message events.

inputSchema describes the shape the agent expects. POST /v1/runs does not check input against it today: an input that does not fit is accepted and reaches the agent rather than being refused, so validate on your side before you send.

List your agents with GET /v1/agents — see the API reference.