Skip to content

README.md

Latest commit

 

History

History
661 lines (521 loc) · 250 KB

README.md

File metadata and controls

661 lines (521 loc) · 250 KB
Raw

Agents

Overview

Available Operations

  • 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

create

Create a new agent with the specified model, instructions, tools, and knowledge bases. Supports fallback models and configurable execution settings.

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.0,
            "on_codes": [
                429.0,
                500.0,
                502.0,
                503.0,
                504.0,
            ],
        },
    }, settings={
        "tools": [
            {
                "type": "mcp",
                "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
                "tool_id": "01KXYZ123456789",
                "requires_approval": False,
            },
        ],
    }, display_name="HR Assistant", fallback_models=[
        {
            "id": "<id>",
            "retry": {
                "count": 3.0,
                "on_codes": [
                    429.0,
                    500.0,
                    502.0,
                    503.0,
                    504.0,
                ],
            },
        },
    ], 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 Answers employee questions about benefits, PTO, and company policies.
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 Project
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 HR Assistant
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.
skills List[str] ➖ List of skills that the agent can utilize. This field allows you to specify which skills the agent has access to, enabling more complex and dynamic behavior.
variables Dict[str, Any] ➖ N/A
source Optional[models.Source] ➖ N/A
engine Optional[models.CreateAgentRequestEngine] ➖ 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.APIDefaultError 4XX, 5XX */*

list

List all agents in the workspace with full configuration details. Supports pagination and sorts agents newest first.

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

    # 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
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.APIDefaultError 4XX, 5XX */*

delete

Permanently remove an agent and all associated configuration from the workspace. Terminate active sessions and the key becomes reusable.

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.APIDefaultError 4XX, 5XX */*

retrieve

Retrieve the complete agent manifest by key, including model assignments, tools, knowledge bases, memory stores, and execution parameters.

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.APIDefaultError 4XX, 5XX */*

update

Partially update an existing agent configuration including models, instructions, tools, knowledge bases, and execution parameters.

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="openai/gpt-5.6-sol", 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.

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.		 Default Project
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.
skills List[str] ➖ List of skills that the agent can utilize. This field allows you to specify which skills the agent has access to, enabling more complex and dynamic behavior.
variables Dict[str, Any] ➖ Extracted variables from agent instructions
engine Optional[models.UpdateAgentEngine] ➖ N/A
version_increment Optional[models.VersionIncrement] ➖ 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.APIDefaultError 4XX, 5XX */*

invoke

Invoke an agent to perform a task with input messages. Supports tool execution, knowledge retrieval, memory context, and model fallback.

⚠️ 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.APIDefaultError 4XX, 5XX */*

run

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

⚠️ 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="openai/gpt-5.6-sol", 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.

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.		 Default Project
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.APIDefaultError 4XX, 5XX */*

stream_run

Run an agent with streaming via SSE, combining inline configuration with real-time updates including messages, tool executions, and status.

⚠️ 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="openai/gpt-5.6-sol", 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.

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.		 Default Project
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.APIDefaultError 4XX, 5XX */*

stream

Stream an existing agent execution in real-time via SSE, providing live message chunks, tool calls, and status updates until completion.

⚠️ 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.APIDefaultError 4XX, 5XX */*