Agents

Overview

Available Operations

post_v2_agents_a2a - Register external A2A agent
post_v2_agents_key_card_refresh - Refresh A2A agent card
create - Create agent
list - List agents
delete - Delete agent
retrieve - Retrieve agent
update - Update agent
~~invoke~~ - Execute an agent task ⚠️ Deprecated
~~run~~ - Run an agent with configuration ⚠️ Deprecated
~~stream_run~~ - Run agent with streaming response ⚠️ Deprecated
~~stream~~ - Stream agent execution in real-time ⚠️ Deprecated

post_v2_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.

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`request`	models.PostV2AgentsA2aRequestBody	✔️	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PostV2AgentsA2aResponseBody

Errors

Error Type	Status Code	Content Type
models.PostV2AgentsA2aAgentsResponseBody	400	application/json
models.PostV2AgentsA2aAgentsResponseResponseBody	409	application/json
models.APIError	4XX, 5XX	/

post_v2_agents_key_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.

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`key`	str	✔️	The unique key identifier of the agent
`request_body`	Optional[models.PostV2AgentsKeyCardRefreshRequestBody]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PostV2AgentsKeyCardRefreshResponseBody

Errors

Error Type	Status Code	Content Type
models.PostV2AgentsKeyCardRefreshAgentsResponseBody	400	application/json
models.PostV2AgentsKeyCardRefreshAgentsResponseResponseBody	404	application/json
models.APIError	4XX, 5XX	/

create

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.

Example 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)

Parameters

Parameter	Type	Required	Description	Example
`key`	str	✔️	Unique identifier for the agent within the workspace
`role`	str	✔️	The role or function of the agent
`description`	str	✔️	A brief description of what the agent does
`instructions`	str	✔️	Detailed instructions that guide the agent's behavior
`path`	str	✔️	The path where the agent will be stored in the project structure. The first element identifies the project, followed by nested folders (auto-created as needed). With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.	Default
`model`	models.ModelConfiguration	✔️	Model configuration for agent execution. Can be a simple model ID string or a configuration object with optional behavior parameters and retry settings.
`settings`	models.CreateAgentRequestSettings	✔️	Configuration settings for the agent's behavior
`display_name`	Optional[str]	➖	agent display name within the workspace
`system_prompt`	OptionalNullable[str]	➖	A custom system prompt template for the agent. If omitted, the default template is used.
`fallback_models`	List[models.FallbackModelConfiguration]	➖	Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
`memory_stores`	List[str]	➖	Optional array of memory store identifiers for the agent to access. Accepts both memory store IDs and keys.
`knowledge_bases`	List[models.KnowledgeBases]	➖	Optional array of knowledge base configurations for the agent to access
`team_of_agents`	List[models.TeamOfAgents]	➖	The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
`variables`	Dict[str, Any]	➖	N/A
`source`	Optional[models.Source]	➖	N/A
`engine`	Optional[models.Engine]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CreateAgentRequestResponseBody

Errors

Error Type	Status Code	Content Type
models.APIError	4XX, 5XX	/

list

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.

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`limit`	Optional[float]	➖	A limit on the number of objects to be returned. Limit can range between 1 and 200. When not provided, returns all agents without pagination.
`starting_after`	Optional[str]	➖	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `after=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the next page of the list.
`ending_before`	Optional[str]	➖	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `before=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the previous page of the list.
`type`	Optional[models.QueryParamType]	➖	Filter agents by type: "internal" for Orquesta-managed agents, "a2a" for external A2A-compliant agents
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.ListAgentsResponseBody

Errors

Error Type	Status Code	Content Type
models.APIError	4XX, 5XX	/

delete

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.

Example Usage

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 ...

Parameters

Parameter	Type	Required	Description
`agent_key`	str	✔️	The unique key of the agent to delete
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Errors

Error Type	Status Code	Content Type
models.DeleteAgentResponseBody	404	application/json
models.APIError	4XX, 5XX	/

retrieve

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.

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`agent_key`	str	✔️	The unique key of the agent to retrieve
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.RetrieveAgentRequestResponseBody

Errors

Error Type	Status Code	Content Type
models.RetrieveAgentRequestAgentsResponseBody	404	application/json
models.APIError	4XX, 5XX	/

update

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.

Example Usage

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)

Parameters

Parameter	Type	Required	Description	Example
`agent_key`	str	✔️	The unique key of the agent to update
`key`	Optional[str]	➖	N/A
`display_name`	Optional[str]	➖	N/A
`project_id`	Optional[str]	➖	N/A
`role`	Optional[str]	➖	N/A
`description`	Optional[str]	➖	A brief description of what the agent does
`instructions`	Optional[str]	➖	N/A
`system_prompt`	OptionalNullable[str]	➖	A custom system prompt template for the agent. If omitted, the default template is used.
`model`	Optional[models.UpdateAgentModelConfiguration]	➖	Model configuration for agent execution. Can be a simple model ID string or a configuration object with optional behavior parameters and retry settings.
`fallback_models`	List[models.UpdateAgentFallbackModelConfiguration]	➖	Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
`settings`	Optional[models.UpdateAgentSettings]	➖	N/A
`path`	Optional[str]	➖	Entity storage path in the format: `project/folder/subfolder/...` The first element identifies the project, followed by nested folders (auto-created as needed). With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.	Default
`memory_stores`	List[str]	➖	Array of memory store identifiers. Accepts both memory store IDs and keys.
`knowledge_bases`	List[models.UpdateAgentKnowledgeBases]	➖	N/A
`team_of_agents`	List[models.UpdateAgentTeamOfAgents]	➖	The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
`variables`	Dict[str, Any]	➖	Extracted variables from agent instructions
`engine`	Optional[models.UpdateAgentEngine]	➖	N/A
`a2a`	Optional[models.UpdateA2AConfiguration]	➖	Update A2A agent configuration (only applicable to A2A agents)
`version_increment`	Optional[models.UpdateAgentVersionIncrement]	➖	Optional semantic version bump to create after a successful publish.
`version_description`	Optional[str]	➖	Optional description stored with the created version.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.UpdateAgentResponseBody

Errors

Error Type	Status Code	Content Type
models.UpdateAgentAgentsResponseBody	404	application/json
models.APIError	4XX, 5XX	/

invoke

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.

⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`key`	str	✔️	The key or ID of the agent to invoke
`message`	models.InvokeAgentA2AMessage	✔️	The A2A message to send to the agent (user input or tool results)
`task_id`	Optional[str]	➖	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.
`variables`	Dict[str, Any]	➖	Optional variables for template replacement in system prompt, instructions, and messages
`identity`	Optional[models.InvokeAgentIdentity]	➖	Information about the identity making the request. If the identity does not exist, it will be created automatically.
`contact`	Optional[models.InvokeAgentContact]	➖	: warning: DEPRECATED : This will be removed in a future release, please migrate away from it as soon as possible. @deprecated Use identity instead. Information about the contact making the request.
`thread`	Optional[models.InvokeAgentThread]	➖	Thread information to group related requests
`memory`	Optional[models.InvokeAgentMemory]	➖	Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
`metadata`	Dict[str, Any]	➖	Optional metadata for the agent invocation as key-value pairs that will be included in traces
`engine`	Optional[models.InvokeAgentEngine]	➖	Override template engine for this invocation. If not provided, uses the agent default.
`configuration`	Optional[models.InvokeAgentConfiguration]	➖	Configuration options for the agent invocation
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.InvokeAgentA2ATaskResponse

Errors

Error Type	Status Code	Content Type
models.APIError	4XX, 5XX	/

run

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.

⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

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)

Parameters

Parameter	Type	Required	Description	Example
`key`	str	✔️	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.
`model`	models.RunAgentModelConfiguration	✔️	Model configuration for this execution. Can override the agent manifest defaults if the agent already exists.
`role`	str	✔️	Specifies the agent's function and area of expertise.
`instructions`	str	✔️	Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.
`message`	models.RunAgentA2AMessage	✔️	The A2A format message containing the task for the agent to perform.
`path`	str	✔️	Entity storage path in the format: `project/folder/subfolder/...` The first element identifies the project, followed by nested folders (auto-created as needed). With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.	Default
`settings`	models.RunAgentSettings	✔️	N/A
`task_id`	Optional[str]	➖	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.
`fallback_models`	List[models.RunAgentFallbackModelConfiguration]	➖	Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
`variables`	Dict[str, Any]	➖	Optional variables for template replacement in system prompt, instructions, and messages
`identity`	Optional[models.RunAgentIdentity]	➖	Information about the identity making the request. If the identity does not exist, it will be created automatically.
`contact`	Optional[models.RunAgentContact]	➖	: warning: DEPRECATED : This will be removed in a future release, please migrate away from it as soon as possible. @deprecated Use identity instead. Information about the contact making the request.
`thread`	Optional[models.RunAgentThread]	➖	Thread information to group related requests
`memory`	Optional[models.RunAgentMemory]	➖	Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
`description`	Optional[str]	➖	A brief summary of the agent's purpose.
`system_prompt`	OptionalNullable[str]	➖	A custom system prompt template for the agent. If omitted, the default template is used.
`memory_stores`	List[str]	➖	Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.
`knowledge_bases`	List[models.RunAgentKnowledgeBases]	➖	Knowledge base configurations for the agent to access
`team_of_agents`	List[models.RunAgentTeamOfAgents]	➖	The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
`metadata`	Dict[str, Any]	➖	Optional metadata for the agent run as key-value pairs that will be included in traces
`engine`	Optional[models.RunAgentEngine]	➖	Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.RunAgentA2ATaskResponse

Errors

Error Type	Status Code	Content Type
models.APIError	4XX, 5XX	/

stream_run

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.

⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

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)

Parameters

Parameter	Type	Required	Description	Example
`key`	str	✔️	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.
`model`	models.StreamRunAgentModelConfiguration	✔️	Model configuration for this execution. Can override the agent manifest defaults if the agent already exists.
`role`	str	✔️	Specifies the agent's function and area of expertise.
`instructions`	str	✔️	Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.
`message`	models.StreamRunAgentA2AMessage	✔️	The A2A format message containing the task for the agent to perform.
`path`	str	✔️	Entity storage path in the format: `project/folder/subfolder/...` The first element identifies the project, followed by nested folders (auto-created as needed). With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.	Default
`settings`	models.StreamRunAgentSettings	✔️	N/A
`task_id`	Optional[str]	➖	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.
`fallback_models`	List[models.StreamRunAgentFallbackModelConfiguration]	➖	Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
`variables`	Dict[str, Any]	➖	Optional variables for template replacement in system prompt, instructions, and messages
`identity`	Optional[models.StreamRunAgentIdentity]	➖	Information about the identity making the request. If the identity does not exist, it will be created automatically.
`contact`	Optional[models.StreamRunAgentContact]	➖	: warning: DEPRECATED : This will be removed in a future release, please migrate away from it as soon as possible. @deprecated Use identity instead. Information about the contact making the request.
`thread`	Optional[models.StreamRunAgentThread]	➖	Thread information to group related requests
`memory`	Optional[models.StreamRunAgentMemory]	➖	Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
`description`	Optional[str]	➖	A brief summary of the agent's purpose.
`system_prompt`	OptionalNullable[str]	➖	A custom system prompt template for the agent. If omitted, the default template is used.
`memory_stores`	List[str]	➖	Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.
`knowledge_bases`	List[models.StreamRunAgentKnowledgeBases]	➖	Knowledge base configurations for the agent to access
`team_of_agents`	List[models.StreamRunAgentTeamOfAgents]	➖	The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
`metadata`	Dict[str, Any]	➖	Optional metadata for the agent run as key-value pairs that will be included in traces
`engine`	Optional[models.StreamRunAgentEngine]	➖	Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax.
`stream_timeout_seconds`	Optional[float]	➖	Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

Union[eventstreaming.EventStream[models.StreamRunAgentResponseBody], eventstreaming.EventStreamAsync[models.StreamRunAgentResponseBody]]

Errors

Error Type	Status Code	Content Type
models.StreamRunAgentAgentsResponseBody	404	application/json
models.APIError	4XX, 5XX	/

stream

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).

⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`key`	str	✔️	The key or ID of the agent to invoke
`message`	models.StreamAgentA2AMessage	✔️	The A2A message to send to the agent (user input or tool results)
`task_id`	Optional[str]	➖	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.
`variables`	Dict[str, Any]	➖	Optional variables for template replacement in system prompt, instructions, and messages
`identity`	Optional[models.StreamAgentIdentity]	➖	Information about the identity making the request. If the identity does not exist, it will be created automatically.
`contact`	Optional[models.StreamAgentContact]	➖	: warning: DEPRECATED : This will be removed in a future release, please migrate away from it as soon as possible. @deprecated Use identity instead. Information about the contact making the request.
`thread`	Optional[models.StreamAgentThread]	➖	Thread information to group related requests
`memory`	Optional[models.StreamAgentMemory]	➖	Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
`metadata`	Dict[str, Any]	➖	Optional metadata for the agent invocation as key-value pairs that will be included in traces
`engine`	Optional[models.StreamAgentEngine]	➖	Override template engine for this invocation. If not provided, uses the agent default.
`configuration`	Optional[models.StreamAgentConfiguration]	➖	Configuration options for the agent invocation
`stream_timeout_seconds`	Optional[float]	➖	Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

Union[eventstreaming.EventStream[models.StreamAgentResponseBody], eventstreaming.EventStreamAsync[models.StreamAgentResponseBody]]

Errors

Error Type	Status Code	Content Type
models.StreamAgentAgentsResponseBody	404	application/json
models.APIError	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Agents

Overview

Available Operations

post_v2_agents_a2a

Example Usage

Parameters

Response

Errors

post_v2_agents_key_card_refresh

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

list

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Errors

retrieve

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

invoke

Example Usage

Parameters

Response

Errors

run

Example Usage

Parameters

Response

Errors

stream_run

Example Usage

Parameters

Response

Errors

stream

Example Usage

Parameters

Response

Errors