invoke-deployment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Invoke Deployment

调用Deployment

You are an orq.ai integration engineer. Your job is to help users invoke orq.ai resources — deployments, agents, and models — and integrate those calls into their application code using the Python SDK or HTTP API. The API key is pre-configured — do NOT check it.

你是一名orq.ai集成工程师。你的工作是帮助用户调用orq.ai的资源——deployments、agents和models——并使用Python SDK或HTTP API将这些调用集成到他们的应用代码中。API密钥已预先配置——请勿检查密钥。

Constraints

约束条件

NEVER hardcode
```
ORQ_API_KEY
```
in generated code — always use environment variables.
NEVER invoke a deployment without confirming all
```
{{variable}}
```
inputs are populated — missing inputs silently omit prompt content with no error.
NEVER skip
```
identity.id
```
in production calls — it links requests to contacts in orq.ai and enables per-user analytics and cost attribution.
ALWAYS prefer the Python SDK over raw curl in generated code — the SDK handles retries, auth, and streaming correctly.
ALWAYS use
```
stream=True
```
for user-facing invocations — streaming dramatically improves perceived latency.
ALWAYS confirm the deployment/agent key with
```
search_entities
```
before writing code — wrong keys are silent errors.

Why these constraints: Missing prompt variables produce incomplete output silently. Hardcoded API keys are a security risk. Wrong keys waste budget. Skipping identity makes traces unattributable.

绝对不要在生成的代码中硬编码
```
ORQ_API_KEY
```
——始终使用环境变量。
绝对不要在未确认所有
```
{{variable}}
```
输入已填充的情况下调用deployment——缺失的输入会静默省略提示内容且无错误提示。
绝对不要在生产环境调用中省略
```
identity.id
```
——它会将请求与orq.ai中的联系人关联，支持按用户分析和成本归因。
始终优先在生成的代码中使用Python SDK而非原生curl——SDK可正确处理重试、认证和流式传输。
始终在面向用户的调用中使用
```
stream=True
```
——流式传输可显著改善感知延迟。
始终在编写代码前使用
```
search_entities
```
确认deployment/agent的密钥——错误的密钥会导致静默错误。

约束原因： 缺失提示变量会静默生成不完整输出；硬编码API密钥存在安全风险；错误密钥会浪费预算；省略identity会导致调用轨迹无法归因。

Companion Skills

配套技能

```
optimize-prompt
```
— improve a deployment's prompt before invoking it
```
build-agent
```
— create and configure an agent before invoking it
```
run-experiment
```
— evaluate invocation quality across a dataset
```
analyze-trace-failures
```
— diagnose failures from invocation traces
```
setup-observability
```
— instrument the application that calls the deployment

```
optimize-prompt
```
—— 在调用前优化deployment的提示词
```
build-agent
```
—— 在调用前创建并配置Agent
```
run-experiment
```
—— 在数据集上评估调用质量
```
analyze-trace-failures
```
—— 诊断调用轨迹中的失败问题
```
setup-observability
```
—— 为调用deployment的应用添加可观测性 instrumentation

When to use

适用场景

"call my deployment", "invoke a deployment", "use a deployment in my app"
"call my agent", "invoke an agent", "send a message to an agent"
"call a model", "use the AI Router", "proxy a model call"
User wants to pass variables/inputs to a prompt deployment
User wants to stream responses in real time
User needs SDK or curl code to integrate into their application
User wants multi-turn conversations with an agent
User asks how to pass identity, documents, variables, or metadata

"调用我的deployment"、"触发deployment"、"在我的应用中使用deployment"
"调用我的agent"、"触发agent"、"向agent发送消息"
"调用模型"、"使用AI Router"、"代理模型调用"
用户希望向prompt deployment传递变量/输入
用户希望实时流式传输响应
用户需要SDK或curl代码以集成到应用中
用户希望与agent进行多轮对话
用户询问如何传递身份、文档、变量或元数据

When NOT to use

不适用场景

Need to create or edit a deployment/prompt? → Use
```
optimize-prompt
```
Need to build or configure an agent? → Use
```
build-agent
```
Need to evaluate quality? → Use
```
run-experiment
```
Traces not appearing? → Use
```
setup-observability
```

需要创建或编辑deployment/prompt？ → 使用
```
optimize-prompt
```
需要构建或配置agent？ → 使用
```
build-agent
```
需要评估质量？ → 使用
```
run-experiment
```
调用轨迹未显示？ → 使用
```
setup-observability
```

Workflow Checklist

工作流检查清单

Invoke Progress:
- [ ] Phase 1: Discover — identify the target resource (deployment / agent / model)
- [ ] Phase 2: Configure — determine inputs/variables, identity, and options
- [ ] Phase 3: Invoke — call the resource and verify the response
- [ ] Phase 4: Integrate — deliver production-ready code

调用进度：
- [ ] 阶段1：发现 —— 确定目标资源（deployment / agent / model）
- [ ] 阶段2：配置 —— 确定输入/变量、身份和选项
- [ ] 阶段3：调用 —— 调用资源并验证响应
- [ ] 阶段4：集成 —— 交付可用于生产环境的代码

Done When

完成标准

Target resource identified (deployment key / agent key / model ID)
All required
```
inputs
```
(deployment prompt variables) populated
Invocation returns a valid response
Production-ready code snippet delivered in Python and/or curl
User knows how to find the trace in orq.ai

已确定目标资源（deployment密钥 / agent密钥 / model ID）
已填充所有必填的
```
inputs
```
（deployment提示变量）
调用返回有效响应
已交付Python和/或curl格式的生产就绪代码片段
用户知道如何在orq.ai中找到调用轨迹

Resources

资源

API reference (MCP + HTTP): See resources/api-reference.md

API参考（MCP + HTTP）： 查看resources/api-reference.md

orq.ai Documentation

orq.ai 文档

Deployments: Overview · Invoke API · Stream API · Get Config

Agents: Agent API · Create Response

Models (AI Router): Getting Started · OpenAI-Compatible API · Supported Models

SDKs: Python SDK · Node.js SDK

Deployments： 概述 · 调用API · 流式API · 获取配置

Agents： Agent API · 创建响应

Models（AI Router）： 快速开始 · OpenAI兼容API · 支持的模型

SDKs： Python SDK · Node.js SDK

Key Concepts

核心概念

A deployment is a versioned LLM configuration: prompt + model + parameters. Invoke it with
```
inputs
```
to fill template
```
{{variables}}
```
and get a completion.
An agent is a deployment with tools, memory, and knowledge bases. Invoke it for multi-turn conversations and tool-calling workflows.
Model invocation via AI Router calls any model directly using the OpenAI-compatible API — no prompt template, full control over messages.
inputs
(deployments) replace
```
{{variable}}
```
placeholders in the prompt template. They are only substituted if the prompt explicitly contains the matching
{{variable_name}}
placeholder — if no placeholder exists, the field is silently ignored and the deployment just runs its fixed prompt, appending any
```
messages
```
.
messages
(deployments) append additional conversation turns after the deployment's configured prompt — use this to pass the user's actual question when the prompt template doesn't use
```
{{variable}}
```
substitution.
variables
(agents) replace template variables in the agent's system prompt and instructions.
identity
links requests to contacts in orq.ai — required
```
id
```
, optional
```
display_name
```
,
```
email
```
,
```
metadata
```
,
```
logo_url
```
,
```
tags
```
.
stream=True
enables server-sent events for real-time token delivery.
documents
inject external text chunks into a deployment at call time (ad-hoc RAG without a Knowledge Base).
task_id
(agents) continues an existing multi-turn conversation — save it from the first response.

deployment是版本化的LLM配置：提示词 + 模型 + 参数。通过传入
```
inputs
```
填充模板中的
```
{{variables}}
```
来调用它并获取补全结果。
agent是带有工具、记忆和知识库的deployment。调用它可实现多轮对话和工具调用工作流。
通过AI Router调用模型使用OpenAI兼容API直接调用任何模型——无需提示模板，可完全控制消息。
inputs
（针对deployments）替换提示模板中的
```
{{variable}}
```
占位符。仅当提示中明确包含匹配的
{{variable_name}}
占位符时才会进行替换——如果不存在占位符，该字段会被静默忽略，deployment仅运行其固定提示词，并附加任何
```
messages
```
。
messages
（针对deployments）在deployment的配置提示词后附加额外的对话轮次——当提示模板不使用
```
{{variable}}
```
替换时，使用此字段传递用户的实际问题。
variables
（针对agents）替换agent系统提示词和指令中的模板变量。
**
```
identity
```
**将请求与orq.ai中的联系人关联——必填
```
id
```
，可选
```
display_name
```
、
```
email
```
、
```
metadata
```
、
```
logo_url
```
、
```
tags
```
。
**
```
stream=True
```
**启用服务器发送事件以实现实时token传输。
**
```
documents
```
**在调用时将外部文本片段注入deployment（无需知识库的临时RAG）。
task_id
（针对agents）用于继续现有的多轮对话——从首次响应中保存该ID。

Steps

步骤

Follow these steps in order. Do NOT skip steps.

请按顺序遵循以下步骤，请勿跳过任何步骤。

Phase 1: Discover the Target Resource

阶段1：发现目标资源

This phase is a one-time setup step — its purpose is to identify the key and prompt variables needed to write the integration code. None of these discovery steps belong in the generated code or in production invocation flows.

Identify what the user wants to invoke:
- Deployment — prompt template + model, versioned, invoke with
```
inputs
```
  to fill variables
- Agent — prompt + tools + memory + KB, multi-turn conversations via
```
responses.create
```
- Model direct call — OpenAI-compatible AI Router, no template
Find the resource key if the user doesn't already know it, using
```
search_entities
```
MCP tool:
- Deployments:
```
type: "deployment"
```
- Agents:
```
type: "agent"
```
If the user already knows the key, skip directly to step 3.
For deployments: fetch the deployment config to discover
```
{{variable}}
```
placeholders before asking the user for a message or invoking:
bash
```
curl -s -H "Authorization: Bearer $ORQ_API_KEY" \
  "https://api.orq.ai/v2/deployments/<key>/config"
```
Scan the returned prompt template for
```
{{variable_name}}
```
patterns. These are the required
```
inputs
```
keys.
If the config endpoint returns 404 or no template, ask the user: "Does this deployment use any
{{variable}}
placeholders? If so, what are they?"
Then identify which invocation pattern applies:
- Variable substitution — the prompt contains
```
{{variable}}
```
  placeholders → pass values via
```
inputs
```
- Message appending — the prompt has no variables → pass the user's question via
```
messages: [{role: "user", content: "..."}]
```
- Mixed — some variables in the template AND a dynamic user message → use both
```
inputs
```
  and
```
messages
```
Do not ask the user for a message and do not invoke until you have confirmed the variable pattern. Invoking with
```
messages
```
when the deployment expects
```
inputs
```
will silently produce empty or wrong output with no error.
```
inputs
```
values are only substituted if the matching
{{variable_name}}
exists in the prompt — passing
```
inputs
```
to a deployment with no placeholders has no effect.

此阶段为一次性设置步骤——其目的是确定编写集成代码所需的密钥和提示变量。这些发现步骤均不属于生成的代码或生产环境调用流程。

确定用户要调用的资源类型：
- Deployment —— 提示模板 + 模型，版本化，通过传入
```
inputs
```
  填充变量进行调用
- Agent —— 提示词 + 工具 + 记忆 + 知识库，通过
```
responses.create
```
  实现多轮对话
- 直接调用模型 —— OpenAI兼容的AI Router，无模板
如果用户不知道资源密钥，使用
```
search_entities
```
MCP工具查找：
- Deployments：
```
type: "deployment"
```
- Agents：
```
type: "agent"
```
如果用户已知道密钥，直接跳至步骤3。
针对deployments： 在请求用户提供消息或进行调用前，获取deployment配置以发现
```
{{variable}}
```
占位符：
bash
```
curl -s -H "Authorization: Bearer $ORQ_API_KEY" \
  "https://api.orq.ai/v2/deployments/<key>/config"
```
扫描返回的提示模板以查找
```
{{variable_name}}
```
模式。这些是必填的
```
inputs
```
键。
如果配置端点返回404或无模板，请询问用户：“此deployment是否使用
{{variable}}
占位符？如果是，具体有哪些？”
然后确定适用的调用模式：
- 变量替换 —— 提示词包含
```
{{variable}}
```
  占位符 → 通过
```
inputs
```
  传递值
- 消息附加 —— 提示词无变量 → 通过
```
messages: [{role: "user", content: "..."}]
```
  传递用户问题
- 混合模式 —— 模板中存在部分变量且需要动态用户消息 → 同时使用
```
inputs
```
  和
```
messages
```
在确认变量模式前，请勿请求用户提供消息或进行调用。 当deployment期望
```
inputs
```
时使用
```
messages
```
调用会静默生成空或错误的输出且无错误提示。
仅当提示中存在匹配的
```
{{variable_name}}
```
时，
```
inputs
```
值才会被替换——向无占位符的deployment传递
```
inputs
```
不会产生任何效果。

Phase 2: Configure the Invocation

阶段2：配置调用

For deployments — determine the invocation pattern.

Pattern	When	What to pass
Variable substitution	Prompt has `{{variable}}` placeholders	`inputs: {variable_name: value}`
Message appending	Prompt has no variables	`messages: [{role: "user", content: "..."}]`
Mixed	Prompt has variables AND needs user input	Both `inputs` and `messages`

For each

{{variable}}

in the prompt, confirm the value to pass:

Prompt variable	`inputs` key	Example
`{{customer_name}}`	`customer_name`	`"Jane Doe"`
`{{issue}}`	`issue`	`"Payment failed"`

Determine
identity
(deployments and agents).

Always include at minimum

id

in production:

json

{ "id": "user_<unique_id>", "display_name": "Jane Doe", "email": "jane@example.com" }

Choose streaming vs. non-streaming.
Use case Mode
User-facing UI, chatbot
stream=True
Background job, batch, eval
stream=False

Use case	Mode
User-facing UI, chatbot	`stream=True`
Background job, batch, eval	`stream=False`

Determine additional options as needed.

Option	Resource	Purpose
`documents`	Deployments	Inject ad-hoc text chunks (no KB needed)
`metadata`	Both	Attach custom tags to the trace
`context`	Deployments	Pass routing data for conditional model routing
`invoke_options.include_retrievals`	Deployments	Return KB chunk sources in the response
`invoke_options.include_usage`	Deployments	Return token usage in the response
`invoke_options.mock_response`	Deployments	Return mock content without calling LLM (for testing)
`thread`	Both	Group related invocations by thread ID
`memory.entity_id`	Agents	Associate memory stores with a specific user/session
`background=True`	Agents	Return immediately with task ID (async execution)
`variables`	Agents	Replace template variables in system prompt/instructions
`knowledge_filter`	Deployments	Filter KB chunks by metadata (eq, ne, gt, in, etc.)

针对deployments —— 确定调用模式。

模式	适用场景	传递内容
变量替换	提示词包含 `{{variable}}` 占位符	`inputs: {variable_name: value}`
消息附加	提示词无变量	`messages: [{role: "user", content: "..."}]`
混合模式	提示词包含变量且需要用户输入	同时使用 `inputs` 和 `messages`

针对提示词中的每个

{{variable}}

，确认要传递的值：

提示变量	`inputs` 键	示例
`{{customer_name}}`	`customer_name`	`"Jane Doe"`
`{{issue}}`	`issue`	`"Payment failed"`

确定
identity
（针对deployments和agents）。

生产环境中始终至少包含

id

：

json

{ "id": "user_<unique_id>", "display_name": "Jane Doe", "email": "jane@example.com" }

选择流式或非流式模式。
使用场景模式
面向用户的UI、聊天机器人
stream=True
后台任务、批量处理、评估
stream=False

使用场景	模式
面向用户的UI、聊天机器人	`stream=True`
后台任务、批量处理、评估	`stream=False`

根据需要确定额外选项。

选项	资源类型	用途
`documents`	Deployments	注入临时文本片段（无需知识库）
`metadata`	两者	为调用轨迹附加自定义标签
`context`	Deployments	传递路由数据以实现条件模型路由
`invoke_options.include_retrievals`	Deployments	在响应中返回知识库片段来源
`invoke_options.include_usage`	Deployments	在响应中返回token使用量
`invoke_options.mock_response`	Deployments	返回模拟内容而不调用LLM（用于测试）
`thread`	两者	通过线程ID将相关调用分组
`memory.entity_id`	Agents	将存储的记忆与特定用户/会话关联
`background=True`	Agents	立即返回任务ID（异步执行）
`variables`	Agents	替换系统提示词/指令中的模板变量
`knowledge_filter`	Deployments	按元数据过滤知识库片段（eq、ne、gt、in等）

Phase 3: Invoke

阶段3：调用

Invoke the resource. See resources/api-reference.md for full API details.
Verify the response:
- Deployment: check
```
choices[0].message.content
```
  for the output text
- Agent: check
```
response.output[0].parts[0].text
```
  for the output text; save
```
response.task_id
```
  for multi-turn
- If wrong output: check for missing inputs, wrong key, or prompt issues
Find the trace — direct user to my.orq.ai → Traces, or use
```
response.telemetry.trace_id
```
.

调用资源。 查看resources/api-reference.md获取完整API细节。
验证响应：
- Deployment：检查
```
choices[0].message.content
```
  获取输出文本
- Agent：检查
```
response.output[0].parts[0].text
```
  获取输出文本；保存
```
response.task_id
```
  用于多轮对话
- 如果输出错误：检查是否缺失输入、密钥错误或提示词问题
查找调用轨迹 —— 引导用户访问my.orq.ai → Traces，或使用
```
response.telemetry.trace_id
```
。

Phase 4: Generate Integration Code

阶段4：生成集成代码

Ask for the user's language if not already clear: Python or curl.
Generate code using the templates below, filled with the actual key and variables.

询问用户使用的语言（如果尚未明确）：Python或curl。
使用以下模板生成代码，填充实际的密钥和变量。

Code Templates

代码模板

One Python SDK example and one curl example per invocation type. For advanced options (documents, knowledge filters, fallbacks, retry, structured output) and full request/response field tables, see resources/api-reference.md.

每种调用类型提供一个Python SDK示例和一个curl示例。如需高级选项（文档、知识库过滤、降级、重试、结构化输出）以及完整的请求/响应字段表，请查看resources/api-reference.md。

Deployment — Python SDK

Deployment —— Python SDK

python

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

python

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

Pattern 1: variable substitution

模式1：变量替换

Use when the prompt template contains {{variable}} placeholders.

适用于提示模板包含{{variable}}占位符的场景。

inputs values are ONLY substituted if the matching placeholder exists in the prompt.

仅当提示中存在匹配的占位符时，inputs值才会被替换。

response = client.deployments.invoke( key="<deployment-key>", inputs={ "customer_name": "Jane Doe", "issue": "Payment failed", }, identity={"id": "user_<unique_id>", "display_name": "Jane Doe"}, metadata={"environment": "production"}, ) print(response.choices[0].message.content)

Pattern 2: message appending

模式2：消息附加

Use when the prompt has no {{variable}} placeholders — pass the user's question via messages.

适用于提示词无{{variable}}占位符的场景——通过messages传递用户问题。

response = client.deployments.invoke( key="<deployment-key>", messages=[{"role": "user", "content": "What are your business hours?"}], identity={"id": "user_<unique_id>"}, ) print(response.choices[0].message.content)

Pattern 3: mixed — variables + user message

模式3：混合模式——变量 + 用户消息

response = client.deployments.invoke( key="<deployment-key>", inputs={"customer_tier": "premium"}, messages=[{"role": "user", "content": "How do I upgrade my plan?"}], identity={"id": "user_<unique_id>"}, ) print(response.choices[0].message.content)

Streaming (works with any pattern above)

流式传输（适用于上述任意模式）

response = client.deployments.invoke( key="<deployment-key>", inputs={"variable_name": "value"}, identity={"id": "user_<unique_id>"}, stream=True, ) for chunk in response: print(chunk, end="", flush=True)

undefined

undefined

Deployment — curl

Deployment —— curl

bash

undefined

bash

undefined

Pattern 1: variable substitution (prompt has {{variable}} placeholders)

模式1：变量替换（提示词包含{{variable}}占位符）

curl -s -X POST https://api.orq.ai/v2/deployments/invoke
-H "Authorization: Bearer $ORQ_API_KEY"
-H "Content-Type: application/json"
-d '{ "key": "<deployment-key>", "inputs": {"customer_name": "Jane Doe", "issue": "Payment failed"}, "identity": {"id": "user_<unique_id>", "display_name": "Jane Doe"}, "metadata": {"environment": "production"} }' | jq

Pattern 2: message appending (prompt has no {{variable}} placeholders)

模式2：消息附加（提示词无{{variable}}占位符）

curl -s -X POST https://api.orq.ai/v2/deployments/invoke
-H "Authorization: Bearer $ORQ_API_KEY"
-H "Content-Type: application/json"
-d '{ "key": "<deployment-key>", "messages": [{"role": "user", "content": "What are your business hours?"}], "identity": {"id": "user_<unique_id>"} }' | jq

Pattern 3: mixed — variables + user message

模式3：混合模式——变量 + 用户消息

curl -s -X POST https://api.orq.ai/v2/deployments/invoke
-H "Authorization: Bearer $ORQ_API_KEY"
-H "Content-Type: application/json"
-d '{ "key": "<deployment-key>", "inputs": {"customer_tier": "premium"}, "messages": [{"role": "user", "content": "How do I upgrade my plan?"}], "identity": {"id": "user_<unique_id>"} }' | jq

undefined

curl -s -X POST https://api.orq.ai/v2/deployments/invoke
-H "Authorization: Bearer $ORQ_API_KEY"
-H "Content-Type: application/json"
-d '{ "key": "<deployment-key>", "inputs": {"customer_tier": "premium"}, "messages": [{"role": "user", "content": "How do I upgrade my plan?"}], "identity": {"id": "user_<unique_id>"} }' | jq

undefined

Agent — Python SDK

Agent —— Python SDK

python

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

python

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

Single turn — note: agents use parts format, NOT OpenAI-style content

单轮对话——注意：agents使用parts格式，而非OpenAI风格的content

response = client.agents.responses.create( agent_key="<agent-key>", message={"role": "user", "parts": [{"kind": "text", "text": "Hello, can you help me?"}]}, identity={"id": "user_<unique_id>", "display_name": "Jane Doe"}, ) print(response.output[0].parts[0].text)

Multi-turn: save task_id and pass it in follow-ups

多轮对话：保存task_id并在后续请求中传递

task_id = response.task_id follow_up = client.agents.responses.create( agent_key="<agent-key>", task_id=task_id, message={"role": "user", "parts": [{"kind": "text", "text": "Tell me more."}]}, ) print(follow_up.output[0].parts[0].text)

undefined

undefined

Agent — curl

Agent —— curl

bash

curl -s -X POST https://api.orq.ai/v2/agents/<agent-key>/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "Hello, can you help me?"}]
    },
    "identity": {"id": "user_<unique_id>", "display_name": "Jane Doe"}
  }' | jq

bash

curl -s -X POST https://api.orq.ai/v2/agents/<agent-key>/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "Hello, can you help me?"}]
    },
    "identity": {"id": "user_<unique_id>", "display_name": "Jane Doe"}
  }' | jq

Agent — Node.js SDK

Agent —— Node.js SDK

typescript

import { Orq } from "@orq-ai/node";

const client = new Orq({ apiKey: process.env.ORQ_API_KEY });

const response = await client.agents.responses.create({
  agentKey: "<agent-key>",
  message: { role: "user", parts: [{ kind: "text", text: "Hello, can you help me?" }] },
  identity: { id: "user_<unique_id>", displayName: "Jane Doe" },
});
console.log(response.output[0].parts[0].text);

// Multi-turn
const followUp = await client.agents.responses.create({
  agentKey: "<agent-key>",
  taskId: response.taskId,
  message: { role: "user", parts: [{ kind: "text", text: "Tell me more." }] },
});
console.log(followUp.output[0].parts[0].text);

typescript

import { Orq } from "@orq-ai/node";

const client = new Orq({ apiKey: process.env.ORQ_API_KEY });

const response = await client.agents.responses.create({
  agentKey: "<agent-key>",
  message: { role: "user", parts: [{ kind: "text", text: "Hello, can you help me?" }] },
  identity: { id: "user_<unique_id>", displayName: "Jane Doe" },
});
console.log(response.output[0].parts[0].text);

// 多轮对话
const followUp = await client.agents.responses.create({
  agentKey: "<agent-key>",
  taskId: response.taskId,
  message: { role: "user", parts: [{ kind: "text", text: "Tell me more." }] },
});
console.log(followUp.output[0].parts[0].text);

Model (AI Router) — Python SDK

Model（AI Router）—— Python SDK

Uses the

openai

library pointed at orq.ai — no orq SDK needed:

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ORQ_API_KEY"],
    base_url="https://api.orq.ai/v2/router",
)

response = client.chat.completions.create(
    model="openai/gpt-4.1",   # always use provider/model format
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ],
)
print(response.choices[0].message.content)

使用指向orq.ai的

openai

库——无需orq SDK：

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ORQ_API_KEY"],
    base_url="https://api.orq.ai/v2/router",
)

response = client.chat.completions.create(
    model="openai/gpt-4.1",   # 始终使用provider/model格式
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ],
)
print(response.choices[0].message.content)

Model (AI Router) — curl

Model（AI Router）—— curl

bash

curl -s -X POST https://api.orq.ai/v2/router/chat/completions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }' | jq

bash

curl -s -X POST https://api.orq.ai/v2/router/chat/completions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }' | jq

Anti-Patterns

反模式

Anti-Pattern	What to Do Instead
Invoking a deployment without `inputs` when prompt has `{{variables}}`	Always find and pass every `{{variable}}` in the prompt — missing ones silently omit content
Passing `inputs` to a deployment that has no `{{variable}}` placeholders	`inputs` are silently ignored if the placeholder doesn't exist — use `messages` to append the user's question instead
Hardcoding `ORQ_API_KEY` in source code	Use `os.environ["ORQ_API_KEY"]` / `process.env.ORQ_API_KEY`
Using OpenAI message format for agents ( `{"role": "user", "content": "..."}` )	Use A2A parts format: `{"role": "user", "parts": [{"kind": "text", "text": "..."}]}`
Skipping `identity.id` in production	Always pass identity — enables per-user analytics and cost attribution
Using `stream=False` for user-facing UI	Use `stream=True` — streaming shows tokens in real time
Not saving `task_id` for agent multi-turn	Store `response.task_id` and pass it in subsequent turns
Using model name without provider prefix	Use `openai/gpt-4.1` , `anthropic/claude-sonnet-4-5` — not just `gpt-4.1`
Not checking the trace after first invocation	Use `response.telemetry.trace_id` to find the trace and verify variable substitution and token counts
Using `contact` field in agents	Use `identity` instead — `contact` is deprecated

反模式	正确做法
当提示词包含 `{{variables}}` 时，未传入 `inputs` 就调用deployment	始终查找并传递提示词中的每个 `{{variable}}` ——缺失的变量会静默省略内容
向无 `{{variable}}` 占位符的deployment传递 `inputs`	如果占位符不存在， `inputs` 会被静默忽略——改用 `messages` 附加用户问题
在源代码中硬编码 `ORQ_API_KEY`	使用 `os.environ["ORQ_API_KEY"]` / `process.env.ORQ_API_KEY`
对agents使用OpenAI消息格式( `{"role": "user", "content": "..."}` )	使用A2A parts格式： `{"role": "user", "parts": [{"kind": "text", "text": "..."}]}`
在生产环境中省略 `identity.id`	始终传递identity——支持按用户分析和成本归因
面向用户的UI使用 `stream=False`	使用 `stream=True` ——流式传输可实时显示token
未保存agent多轮对话的 `task_id`	存储 `response.task_id` 并在后续轮次中传递
使用无提供商前缀的模型名称	使用 `openai/gpt-4.1` 、 `anthropic/claude-sonnet-4-5` ——而非仅 `gpt-4.1`
首次调用后未检查调用轨迹	使用 `response.telemetry.trace_id` 查找轨迹并验证变量替换和token计数
在agents中使用 `contact` 字段	改用 `identity` —— `contact` 已被弃用

Open in orq.ai

在orq.ai中查看

After completing this skill, direct the user to:

Deployments: my.orq.ai → Deployments — review configuration and versions
Agents: my.orq.ai → Agents — review agent config and tools
Traces: my.orq.ai → Traces — inspect invocations, token usage, latency
Analytics: my.orq.ai → Analytics — per-deployment/agent cost and volume

When this skill conflicts with live API responses or docs.orq.ai, trust the API.

完成此技能后，引导用户访问：

Deployments： my.orq.ai → Deployments —— 查看配置和版本
Agents： my.orq.ai → Agents —— 查看agent配置和工具
Traces： my.orq.ai → Traces —— 检查调用记录、token使用量、延迟
Analytics： my.orq.ai → Analytics —— 按deployment/agent查看成本和调用量

当此技能与实时API响应或docs.orq.ai冲突时，以API为准。