Skip to main content

​
Agents

​
Agents A2A

Register an external A2A-compliant agent into Orquesta. The agent card will be fetched during registration to validate the agent and cache its capabilities. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.post_v2_agents_a2a()

    # Handle response
    print(res)

​
Agents Card Refresh

Fetches the latest agent card from the external A2A agent and updates the cached card in the database. Similar to MCP server refresh functionality. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.post_v2_agents_key_card_refresh(key="<key>")

    # Handle response
    print(res)

​
Create an Agent

Creates a new agent with the specified configuration, including model selection, instructions, tools, and knowledge bases. Agents are intelligent assistants that can execute tasks, interact with tools, and maintain context through memory stores. The agent can be configured with a primary model and optional fallback models for automatic failover, custom instructions for behavior control, and various settings to control execution limits and tool usage. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.create(key="<key>", role="<value>", description="alongside beneath doubtfully behest validity bah after furthermore", instructions="<value>", path="Default", model={
        "id": "<id>",
        "retry": {
            "count": 3,
            "on_codes": [
                429,
                500,
                502,
                503,
                504,
            ],
        },
    }, settings={
        "tools": [
            {
                "type": "mcp",
                "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
                "tool_id": "01KXYZ123456789",
                "requires_approval": False,
            },
        ],
    }, fallback_models=[
        {
            "id": "<id>",
            "retry": {
                "count": 3,
                "on_codes": [
                    429,
                    500,
                    502,
                    503,
                    504,
                ],
            },
        },
    ], knowledge_bases=[
        {
            "knowledge_id": "customer-knowledge-base",
        },
    ], engine="text")

    # Handle response
    print(res)

​
List Agents

Retrieves a comprehensive list of agents configured in your workspace. Supports pagination for large datasets and returns agents sorted by creation date (newest first). Each agent in the response includes its complete configuration: model settings with fallback options, instructions, tools, knowledge bases, memory stores, and execution parameters. Use pagination parameters to efficiently navigate through large collections of agents. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.list(limit=10)

    # Handle response
    print(res)

​
Delete an Agent

Permanently removes an agent from the workspace. This operation is irreversible and will delete all associated configuration including model assignments, tools, knowledge bases, memory stores, and cached data. Active agent sessions will be terminated, and the agent key will become available for reuse. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.agents.delete(agent_key="<value>")

    # Use the SDK ...

​
Retrieve an Agent

Retrieves detailed information about a specific agent identified by its unique key or identifier. Returns the complete agent manifest including configuration settings, model assignments (primary and fallback), tools, knowledge bases, memory stores, instructions, and execution parameters. Use this endpoint to fetch the current state and configuration of an individual agent. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.retrieve(agent_key="<value>")

    # Handle response
    print(res)

​
Update an Agent

Modifies an existing agent’s configuration with partial updates. Supports updating any aspect of the agent including model assignments (primary and fallback), instructions, tools, knowledge bases, memory stores, and execution parameters. Only the fields provided in the request body will be updated; all other fields remain unchanged. Changes take effect immediately for new agent invocations. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.update(agent_key="<value>", model="El Camino", fallback_models=[
        "<value>",
    ], settings={
        "tools": [
            {
                "type": "mcp",
                "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
                "tool_id": "01KXYZ123456789",
                "requires_approval": False,
            },
        ],
    }, path="Default", knowledge_bases=[
        {
            "knowledge_id": "customer-knowledge-base",
        },
    ])

    # Handle response
    print(res)

​
Invoke an Agent [deprecated]

Invokes an agent to perform a task with the provided input message. The agent will process the request using its configured model and tools, maintaining context through memory stores if configured. Supports automatic model fallback on primary model failure, tool execution, knowledge base retrieval, and continuation of previous conversations. Returns a task response that can be used to track execution status and retrieve results. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.invoke(key="<key>", message={
        "role": "user",
        "parts": [],
    }, 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",
        ],
    }, thread={
        "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "tags": [
            "customer-support",
            "priority-high",
        ],
    })

    # Handle response
    print(res)

​
Run an Agent [deprecated]

Executes an agent using inline configuration or references an existing agent. Supports dynamic agent creation where the system automatically manages agent versioning - reusing existing agents with matching configurations or creating new versions when configurations differ. Ideal for programmatic agent execution with flexible configuration management. The agent processes messages in A2A format with support for memory context, tool execution, and automatic model fallback on failure. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(key="<key>", model="F-150", role="<value>", instructions="<value>", message={
        "role": "tool",
        "parts": [
            {
                "kind": "text",
                "text": "<value>",
            },
        ],
    }, path="Default", settings={}, fallback_models=[
        "<value>",
    ], 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",
        ],
    }, thread={
        "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "tags": [
            "customer-support",
            "priority-high",
        ],
    }, knowledge_bases=[
        {
            "knowledge_id": "customer-knowledge-base",
        },
    ], engine="text")

    # Handle response
    print(res)

​
Stream Run [deprecated]

Dynamically configures and executes an agent while streaming the interaction in real-time via Server-Sent Events (SSE). Intelligently manages agent versioning by reusing existing agents with matching configurations or creating new versions when configurations differ. Combines the flexibility of inline configuration with real-time streaming, making it ideal for dynamic agent interactions with live feedback. The stream provides continuous updates including message chunks, tool executions, and status changes until completion or timeout. 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.stream_run(key="<key>", model="Alpine", role="<value>", instructions="<value>", message={
        "role": "user",
        "parts": [
            {
                "kind": "file",
                "file": {
                    "uri": "https://jumbo-zebra.info/",
                },
            },
        ],
    }, path="Default", settings={}, fallback_models=[
        "<value>",
    ], 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",
        ],
    }, thread={
        "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "tags": [
            "customer-support",
            "priority-high",
        ],
    }, knowledge_bases=[
        {
            "knowledge_id": "customer-knowledge-base",
        },
    ], engine="text")

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

​
Stream an Agent [deprecated]

Executes an agent and streams the interaction in real-time using Server-Sent Events (SSE). Provides live updates as the agent processes the request, including message chunks, tool calls, and execution status. Perfect for building responsive chat interfaces and monitoring agent progress. The stream continues until the agent completes its task, encounters an error, or reaches the configured timeout (default 30 minutes, configurable 1-3600 seconds). 
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.stream(key="<key>", message={
        "role": "user",
        "parts": [],
    }, 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",
        ],
    }, thread={
        "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "tags": [
            "customer-support",
            "priority-high",
        ],
    })

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)