Sending input

Every message or control action you send to an agent starts as an agent input (ain_…). Omnara stores the input first, then adds it to the timeline as a durable agent_input event when the agent processes it. This lets a busy agent accept new messages without interrupting its current work. There are four input kinds. You only create the first directly; the others are produced by their own endpoints:

`input_kind`	Created by
`content`	`POST /inputs` — the messages this page is about
`interaction_response`	Resolving an interaction
`control`	Stop current work
`config_change`	Changing the config mid-conversation

export BASE="$OMNARA_API/orgs/$ORG/projects/$PROJ"
export AGENT="agt_v4qtrwz3jehcyd5n6a2bfgik7m"

Send a message

API
Dashboard

The examples assume the client, orgID, and projectID setup from the quickstart, with the $AGENT ID above available as agentID for the SDK. The CLI has no command for sending input — use the REST API or the SDK.

curl "$BASE/agents/$AGENT/inputs" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-8f2c1a" \
  -d '{
    "content_blocks": [
      { "type": "text", "text": "Also check whether the deadline moved." }
    ]
  }'

const input = await sdk.createAgentInput({
  client,
  path: { orgID, projectID, agentID },
  headers: { 'Idempotency-Key': 'reply-8f2c1a' },
  body: {
    content_blocks: [
      { type: 'text', text: 'Also check whether the deadline moved.' },
    ],
  },
})
console.log(input.data.agent_input)

{
  "agent_input": {
    "id": "ain_2bfgik7mv4qtrwz3jehcyd5n6a",
    "state": "received",
    "delivery_mode": "queued",
    "...": "..."
  }
}

state: received means Omnara accepted the input. When the agent processes it, the state becomes resolved and a matching event appears on the timeline. An input can instead become canceled or rejected if it is withdrawn or cannot be delivered.If your system retries requests, send an Idempotency-Key to avoid delivering the same message twice.

Full schema and playground: Create agent input.

Attach files and images

An input can include files alongside text. Inline files are base64-encoded, with limits of 10 MiB per file, 24 MiB combined, and 20 files per input:

jq -n --arg data "$(base64 < chart.png)" '{
  content_blocks: [
    { type: "text", text: "Does this chart match the numbers you found?" },
    { type: "media", media_type: "image/png", filename: "chart.png", data: $data }
  ]
}' |
curl "$BASE/agents/$AGENT/inputs" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @-

import { readFile } from 'node:fs/promises'

const chart = await readFile('chart.png')

await sdk.createAgentInput({
  client,
  path: { orgID, projectID, agentID },
  body: {
    content_blocks: [
      { type: 'text', text: 'Does this chart match the numbers you found?' },
      {
        type: 'media',
        media_type: 'image/png',
        filename: 'chart.png',
        data: chart.toString('base64'),
      },
    ],
  },
})

Omnara accepts common images, PDFs, text files, spreadsheets, and Office documents. It stores each file as an artifact and replaces the inline data with a media_ref in the timeline.

Queued vs steering

delivery_mode decides when a busy agent receives a message:

queued (default) waits until the agent is ready to start new work. Use it for a new task or follow-up.
steering joins the current turn at the next model call, ahead of queued messages. Use it for an urgent correction such as “stop using the staging database.”

The other input kinds — interaction responses, cancels, config changes — never wait in the queue: they’re delivered with a third mode, immediate, that you can’t choose. Only content inputs take queued or steering.

curl "$BASE/agents/$AGENT/inputs" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_mode": "steering",
    "cancel_open_interactions": true,
    "content_blocks": [ { "type": "text", "text": "Ignore the 2024 draft — it was superseded." } ]
  }'

await sdk.createAgentInput({
  client,
  path: { orgID, projectID, agentID },
  body: {
    delivery_mode: 'steering',
    cancel_open_interactions: true,
    content_blocks: [
      { type: 'text', text: 'Ignore the 2024 draft — it was superseded.' },
    ],
  },
})

If the agent is idle, both modes deliver immediately; the difference only exists under load. For a steering message, set cancel_open_interactions: true when the correction makes an open approval or question irrelevant. Omnara cancels those interactions before delivering the message. This field is only valid with delivery_mode: "steering".

Inspect and manage the queue

The queue is API-only for now; the dashboard has no queue view. Through the API, you can list waiting inputs, change their order or delivery mode, or cancel them.

List waiting inputs

curl "$BASE/agents/$AGENT/inputs/backlog" \
  -H "Authorization: Bearer $OMNARA_TOKEN"

const backlog = await sdk.listQueuedBacklogInputs({
  client,
  path: { orgID, projectID, agentID },
})
console.log(backlog.data)

{
  "data": [
    { "id": "ain_2bfgik7mv4qtrwz3jehcyd5n6a", "state": "received", "delivery_mode": "queued", "...": "..." },
    { "id": "ain_4qtrwz3jehcyd5n6a2bfgik7mv", "state": "received", "delivery_mode": "queued", "...": "..." }
  ],
  "next_cursor": null
}

Similarly, you can cancel a queued input, change its position, or switch it between queued and steering delivery. These operations work only while the input is still waiting; if the agent has already taken it, the API returns 409.

Full schemas and playground: List queued backlog inputs · Cancel · Move · Promote · Demote.

Change the config mid-conversation

You can change which config an agent uses without restarting its conversation. Send the new config source to switch models, tools, permissions, or instructions. Omnara validates the config and records the change on the timeline. This is not available in the dashboard yet.

npx omnara agents update {agent-id} --file agent-v2.yaml

jq -n --rawfile src agent-v2.yaml '{source: $src, source_format: "yaml"}' |
curl "$BASE/agents/$AGENT/config" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @-

import { readFile } from 'node:fs/promises'

const source = await readFile('agent-v2.yaml', 'utf8')

await sdk.updateAgentConfig({
  client,
  path: { orgID, projectID, agentID },
  body: { source, source_format: 'yaml' },
})

The change takes effect at the next model call. The dashboard marks it in the conversation with an Agent configuration changed divider.

Full schema and playground: Update agent config.

Who said that? Actors and attribution

Every input is attributed to whoever authenticated the request. When a person calls the API with their own token, that’s exactly what you want. But often the people talking to your agent aren’t Omnara users at all — they’re your customers, typing into your chat frontend or ticketing system. Your backend relays their messages with its own token, so without help the timeline would credit every message to that one backend identity. An actor solves this. It’s not another kind of account — it’s a lightweight identity record for an external user, and passing actor on an input names who actually spoke:

curl "$BASE/agents/$AGENT/inputs" \
  -H "Authorization: Bearer $OMNARA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_blocks": [ { "type": "text", "text": "Customer says the export is still failing." } ],
    "actor": {
      "provider_tenant_id": "acme-support",
      "provider_user_id": "user-3841",
      "display_name": "Dana R."
    }
  }'

await sdk.createAgentInput({
  client,
  path: { orgID, projectID, agentID },
  body: {
    content_blocks: [
      { type: 'text', text: 'Customer says the export is still failing.' },
    ],
    actor: {
      provider_tenant_id: 'acme-support',
      provider_user_id: 'user-3841',
      display_name: 'Dana R.',
    },
  },
})

Omnara reuses an actor when its provider_tenant_id and provider_user_id match an existing record. You can also pass an actor when resolving an interaction or stopping current work. Actors belong to a project and can be listed, fetched, or created through the API. Omit actor when the request is authenticated as an Omnara user; their account already provides the attribution.

Full schemas and playground: List project actors · Upsert an external actor · Get a project actor.

Streaming events

Watch your input get admitted and answered, live

Approvals & questions

Resolve the prompts that pause an agent

Get started

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Examples

Send a message

Attach files and images

Queued vs steering

Inspect and manage the queue

List waiting inputs

Change the config mid-conversation

Who said that? Actors and attribution

Next

Streaming events

Approvals & questions

​Send a message

​Attach files and images

​Queued vs steering

​Inspect and manage the queue

​List waiting inputs

​Change the config mid-conversation

​Who said that? Actors and attribution

​Next

Streaming events

Approvals & questions

Send a message

Attach files and images

Queued vs steering

Inspect and manage the queue

List waiting inputs

Change the config mid-conversation

Who said that? Actors and attribution

Next