ORorq-ai
Agents

Run an agent with configuration

Changed on

Run an agent with inline configuration or existing agent reference. Supports A2A messages, memory context, tool execution, and model fallback.

post/v2/agents/run

Request

  • Base URL
    https://my.orq.ai
  • URL
    https://my.orq.ai/v2/agents/run
  • Auth
    HTTP bearer

Request body

keystring required

A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed.

task_idstring

Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.

rolestring required

Specifies the agent's function and area of expertise.

instructionsstring required

Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.

variablesobject

Optional variables for template replacement in system prompt, instructions, and messages

pathstring required

Entity storage path.

With workspace-level API keys, use the format project/folder/subfolder/.... The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: Default Project/agents.

With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: agents. For backward compatibility, a leading project name is ignored when it matches the scoped project.

descriptionstring

A brief summary of the agent's purpose.

system_promptstring nullable

A custom system prompt template for the agent. If omitted, the default template is used.

memory_storesstring[]

Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.

metadataobject

Optional metadata for the agent run as key-value pairs that will be included in traces

engine'text' | 'jinja' | 'mustache'

Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax.

Example request

{
  "model": "openai/gpt-5.6-sol",
  "fallback_models": [
    {
      "parameters": {
        "fallbacks": [
          {
            "model": "openai/gpt-5.4-mini"
          }
        ],
        "cache": {
          "ttl": 3600
        },
        "load_balancer": {
          "type": "weight_based",
          "models": [
            {
              "model": "openai/gpt-4o",
              "weight": 0.7
            },
            {
              "model": "anthropic/claude-3-5-sonnet",
              "weight": 0.3
            }
          ]
        },
        "timeout": {
          "call_timeout": 30000
        }
      },
      "retry": {
        "count": 3,
        "on_codes": [
          429,
          500,
          502,
          503,
          504
        ]
      }
    }
  ],
  "message": {
    "parts": [
      {
        "file": {
          "uri": "https://example.com/report.pdf"
        }
      }
    ]
  },
  "identity": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "thread": {
    "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "tags": [
      "customer-support",
      "priority-high"
    ]
  },
  "path": "Default Project",
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ]
}

Response

Agent execution initiated successfully. Returns task details including the task ID, execution status, and agent response. The task ID can be used to track execution progress and retrieve results.

idstring required

The unique ID of the created agent execution task

contextIdstring required

The correlation ID for this execution (used for tracking)

kind'task' required

A2A entity type identifier

metadataobject

Task metadata containing workspace_id and trace_id for feedback and tracking

Example response

{
  "status": {
    "message": {
      "parts": [
        {
          "file": {
            "uri": "https://example.com/report.pdf"
          }
        }
      ]
    }
  },
  "messages": [
    {
      "parts": [
        {
          "file": {
            "uri": "https://example.com/report.pdf"
          }
        }
      ]
    }
  ]
}

Changes

  • 928a71e92252Revision changes
    • 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

      the request property default value changed from 01M640RMG04PH9QHGD8Z40KB96 to 01M644XDRP4R49HVMCVFMAVM7R

    • info

      added between_tools discriminator mapping keys to the //// request property

    • info

      added between_tools discriminator mapping keys to the /// request property

    • info

      added to the //// request property oneOf list

    • info

      added to the /// request property oneOf list

  • 33d63277cd4eRevision changes
    • breaking

      removed from the //// request property oneOf list

    • breaking

      removed from the /// request property oneOf list

    • warning

      removed the request property //////

    • warning

      removed the request property //////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • info

      the request property default value changed from 01M63PG4XM9CND24TMVB3NW52X to 01M640RMG04PH9QHGD8Z40KB96

    • info

      removed between_tools discriminator mapping keys from the //// request property

    • info

      removed between_tools discriminator mapping keys from the /// request property