Agents

Who answers a run, and how to shape them.

An agent is a named configuration: instructions, the tools it may use, who it can hand work to, and which of its tool calls need a person's approval. Every run is started against one agent.

Choosing the agent for a run

The agent is the {agentId} segment of the path: POST /v1/agents/{agentId}/runs (and /runs/await, /runs/submit). It is the agent's slug, and it is the only way to choose one — the request body has no agent field.

• amy is the default coordinator, present in every organisation. Use it until you have a reason not to. One reason: it asks before it saves a fact (remember) and every time it forgets one (forget), so an unattended run that tries pauses at awaiting_approval. For unattended runs, create your own agent and set those approval levels.
• An agent you create is reached by its own slug, exactly as written (slugs are lowercase and case-sensitive).
• A slug that does not exist, an agent set to Inactive, a specialist, or an agent your organisation is not entitled to all answer the same way: a 404, with nothing to say which of those it was.

curl -X POST https://api.askamy.co.za/v1/agents/support-triage/runs/await \
  -H "X-Api-Key: $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Customer says their invoice total is wrong.",
    "endUserRef": "user_8841"
  }'

const response = await fetch('https://api.askamy.co.za/v1/agents/support-triage/runs/await', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.AMY_API_KEY!,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Customer says their invoice total is wrong.',
    endUserRef: 'user_8841'
  })
});

if (response.status === 404) {
  // No active, directly addressable agent with that slug in this organisation.
}
const run = await response.json(); // { runId, status, message, usage, … }

Create your own agent

An organisation Admin creates agents in the Console: Console → Agents → New agent. Agents are managed there rather than over the /v1 API, because an agent changes what every future run can do. The form has:

Operational overrides

The New agent form does not set a model or any limits. Those live on the agent's own page: Console → Agents, then the agent, then Operational overrides. An organisation Admin can set these for that agent's runs only:

• Model — a model from any provider your organisation has a key for. Blank means the organisation's default model.
• Parallel tool calls, Max parallel sub-agents and Max delegation depth — how much work the agent may run at once, and how deep a chain of hand-offs may go.
• Max iterations, Max output tokens, Max web searches per run and Max image analyses per run — the ceilings on one run. The defaults are on Limits.

A blank field inherits the default, and Remove override (revert to defaults) clears them all.

The model

A run's model is chosen in this order, and the first that applies wins:

1. The model field of the run request, if it carries one.
2. The model set on the agent's own page, under Operational overrides, if an Admin set one.
3. The organisation's default model, chosen in Console → AI Providers (see Set up your organisation).

To run a model from another provider for one agent, set it on that agent's page. The per-run model field only reaches OpenAI, as below.

A run may carry an optional model field. It is a model id (letters, digits and . _ - : / @, starting with a letter or digit, up to 100 characters) and it overrides the agent's model for that run only; omit it to use the agent's or the organisation's. Three things to know before you use it:

• It is sent to the openai provider. The request has no provider field, so a per-run model only works when your organisation's chat key is an OpenAI key. If your chat key is with another provider, leave model out and set the model on the agent's page, or choose the organisation's default in the Console.
• It is checked like any model. The run is refused before it starts if the organisation has no key for that provider (422 no_provider_credential), if its privacy policy forbids the call (422 inference_policy_unsatisfied), or if Amy has no price on record for the model (422 model_unpriced, with the provider and model named in the body).
• It is kept for approvals. A run paused for approval resumes on the same model; you do not send it again.

{
  "message": "Summarise this ticket.",
  "model": "a-model-id-your-openai-key-can-use"
}

Product-specific agents

Some agents are built for a particular product and are delivered to an organisation as part of an agreement, rather than created by the customer. If you need one, the Amy team sets it up with you during onboarding; until it is enabled for your organisation, a run on its slug is the same 404 as any unknown agent.

Not on the /v1 API

Agents are created and edited in the Console only; the /v1 API does not list or change them. Your code needs just the slug, and a mistyped one shows up at once as a 404 on the first call.

Next

• Tools and MCP — connect your own systems as tools.
• Runs — stream, await or submit.
• Approvals — pausing a run for a person.