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": { … } }'

Versioned behavior

An agent’s behavior is pinned at the moment a run starts — the prompt version, skill versions, model routing, and policies in effect are snapshotted onto the run. Editing the agent afterwards doesn’t change runs that are already in flight, which keeps results reproducible.

Input and output contracts

An agent may declare an inputSchema and an outputSchema. When it does, input you send is validated at admission, and a successful run’s output is a structured object matching the output schema. Agents without an outputSchema return their final assistant message as the result.

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