Agents

Create agent

Changed on

Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission. Reusing an idempotency key returns the current agent even if the retry body differs. The retry body is not applied and integration references are not resolved again.

post/orgs/{orgID}/projects/{projectID}/agents

Request

  • Base URL: https://api.omnara.com/v1
  • URL: https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Host-omnara_session and API key in header X-Omnara-Csrf

Headers

Idempotency-Keystring

Idempotency key for replay-safe mutating requests.

Request body

profilestring
configstring required
namestring

Agent name. Empty means the agent is unnamed; non-empty values use the ResourceName policy.

messagestring

Optional initial text message. Mutually exclusive with initial_input.

toolsobject

Additional integration tool entries (int__<integration-name>__<operation>) and optional list_interaction_handlers or set_interaction_handler tools for this agent. Other tool names are not accepted here. Existing config entries win unchanged. Requires project management permission. The derived config is created atomically with the agent and initial input; the profile is unchanged.

interaction_handlersobject

Additional integration interaction handlers, keyed by immutable integration name with empty object values. Slack and Discord handlers require an assigned conversation and accept empty runtime args. Adding a handler does not assign a conversation. Existing entries win unchanged. Requires project management permission.

Response

Current state of the previously created agent.

Changes

  • 680248a0ba72Revision changes
    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

  • 0a5562d0d229Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status