Orq.ai

https://docs.orq.ai/docs/
Admin
Orq.ai is a generative AI collaboration platform that enables teams to build, deploy, and optimize...
Tokens:514,842
Snippets:4,919
Trust Score:8.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Started with AI Router Setup

Source: https://docs.orq.ai/docs/integrations/code-assistants/overview

Use `search_docs` to find onboarding content for the AI Router, including setup steps, configuration options, and examples.

```python
search_docs("Show me how to set up the AI Router")
```

--------------------------------

### Get Started with Orq.ai Product Areas

Source: https://docs.orq.ai/docs/workspace-mcp

Use `search_docs` to retrieve setup guides and examples for specific product areas, such as configuring the AI Router.

```python
from orq import search_docs

response = search_docs("Show me how to set up the AI Router")
print(response)
```

--------------------------------

### Get Started with Product Area Documentation

Source: https://docs.orq.ai/docs/integrations/code-assistants/mcp

Find and retrieve onboarding information for a specific product area, like setting up the AI Router. This includes setup steps, configuration details, and quick-start examples.

```Orchestrate.ai CLI
Show me how to set up the AI Router
```

--------------------------------

### Run Orq Quickstart Command in Claude Code

Source: https://docs.orq.ai/docs/integrations/code-assistants/skills

Executes the interactive onboarding command in Claude Code to verify the installation and setup of Orq skills.

```bash
/orq:quickstart
```

--------------------------------

### Run Python Server

Source: https://docs.orq.ai/docs/memory-stores/using-memory-stores

Start the Python example server for the external knowledge base. The server will reload automatically on changes.

```bash
uvicorn main:app --reload
```

--------------------------------

### Run Node.js Server

Source: https://docs.orq.ai/docs/memory-stores/using-memory-stores

Start the Node.js example server for the external knowledge base. Use 'npm run dev' for development.

```bash
npm run dev
```

--------------------------------

### Basic LangChain Graph Setup and Execution

Source: https://docs.orq.ai/docs/langchain-1

Instrument your LangChain application with `orq_ai_sdk.langchain.setup()` at the entry point. This example demonstrates setting up a simple stateful graph with a chatbot node and executing it synchronously.

```python
from orq_ai_sdk.langchain import setup

setup()

from typing import Annotated
from typing_extensions import TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

graph_builder = StateGraph(State)
llm = ChatOpenAI(model="gpt-4o", temperature=0.2)

def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages")]}

graph_builder.add_node("chatbot", chatbot)
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)

graph = graph_builder.compile()

result = graph.invoke({"messages": [{"role": "user", "content": "Hello!"}]})
print(result["messages"][-1].content)

```

--------------------------------

### Basic Semantic Kernel and Orq.ai Integration Example

Source: https://docs.orq.ai/docs/proxy/frameworks/semantic-kernel

A complete Python example demonstrating how to initialize Semantic Kernel with Orq.ai's AI Router, set up chat completion, and get a response to a user query. Ensure your ORQ_API_KEY environment variable is set.

```python
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import (
    OpenAIChatCompletion,
    OpenAIChatPromptExecutionSettings
)
from semantic_kernel.contents import ChatHistory
import asyncio
import os

async def main():
    # Configure client with Orq.ai
    client = AsyncOpenAI(
        api_key=os.getenv("ORQ_API_KEY"),
        base_url="https://api.orq.ai/v3/router"
    )

    # Create kernel
    kernel = Kernel()

    # Add chat completion service
    chat_service = OpenAIChatCompletion(
        ai_model_id="gpt-4o",
        async_client=client
    )
    kernel.add_service(chat_service)

    # Create execution settings
    settings = OpenAIChatPromptExecutionSettings(
        max_tokens=2000,
        temperature=0.7
    )

    # Create chat history
    history = ChatHistory()
    history.add_user_message("What is quantum computing?")

    # Get response
    response = await chat_service.get_chat_message_content(
        chat_history=history,
        settings=settings,
        kernel=kernel
    )

    print(response.content)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Few-Shot Learning Example Structure

Source: https://docs.orq.ai/docs/prompts/engineering-guide

Provide examples in a user-assistant format to guide model behavior for few-shot learning.

```bash
## Examples

User: What's the weather like?
Assistant: I don't have access to real-time weather data. Please check a weather service.

User: Tell me about cats.
Assistant: Cats are domestic mammals known for their independence and agility...

## Your Task
Now respond to user questions following the pattern above.
```

--------------------------------

### Install Node.js Server Dependencies

Source: https://docs.orq.ai/docs/memory-stores/using-memory-stores

Install the necessary Node.js packages for the example external knowledge base server using npm.

```bash
npm install
```

--------------------------------

### Basic Agent Example with Orq.ai

Source: https://docs.orq.ai/docs/proxy/frameworks/crewai

A simple CrewAI agent setup using the Orq.ai AI Router for LLM calls. This example demonstrates configuring an agent with the custom LLM and running a basic task.

```python
from crewai import Agent, Task, Crew, LLM
import os

llm = LLM(
    model="openai/gpt-4o",
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router",
)

researcher = Agent(
    role="Research Analyst",
    goal="Provide accurate and concise information on topics",
    backstory="Expert analyst with broad knowledge across many domains.",
    llm=llm,
)

task = Task(
    description="In two sentences, explain what machine learning is.",
    agent=researcher,
    expected_output="A concise two-sentence explanation of machine learning.",
)

crew = Crew(agents=[researcher], tasks=[task], tracing=False)
result = crew.kickoff()
print(result)
```

--------------------------------

### Async LangChain Graph Setup and Execution

Source: https://docs.orq.ai/docs/langchain-1

Instrument your LangChain application with `orq_ai_sdk.langchain.setup()` for asynchronous execution. This example shows setting up a stateful graph and invoking it asynchronously using `asyncio`.

```python
from orq_ai_sdk.langchain import setup

setup()

import asyncio
from typing import Annotated
from typing_extensions import TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

graph_builder = StateGraph(State)
llm = ChatOpenAI(model="gpt-4o", temperature=0.2)

def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages")]}

graph_builder.add_node("chatbot", chatbot)
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)

graph = graph_builder.compile()

async def main():
    result = await graph.ainvoke({"messages": [{"role": "user", "content": "Hello!"}]})
    print(result["messages"][-1].content)

asyncio.run(main())

```

--------------------------------

### Install Python Server Dependencies

Source: https://docs.orq.ai/docs/memory-stores/using-memory-stores

Install the necessary Python packages for the example external knowledge base server using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Instructor and OpenTelemetry Packages

Source: https://docs.orq.ai/docs/proxy/frameworks/instructor

Install the core Instructor library, OpenAI client, and necessary OpenTelemetry packages for tracing. This command installs the OpenInference instrumentation for Instructor.

```bash
# Core Instructor and OpenTelemetry packages
pip install instructor openai opentelemetry-sdk opentelemetry-exporter-otlp

# OpenInference instrumentation for Instructor
pip install openinference-instrumentation-instructor
```

--------------------------------

### Install Instructor and OpenAI Libraries

Source: https://docs.orq.ai/docs/proxy/frameworks/instructor

Install the necessary Python libraries for Instructor and OpenAI integration.

```bash
pip install instructor openai
```

--------------------------------

### Install Node.js SDKs

Source: https://docs.orq.ai/docs/experiments/build

Install the necessary Node.js packages for using the evaluatorq framework and orq-ai-node.

```bash
npm install @orq-ai/evaluatorq
npm install @orq-ai/node
```

--------------------------------

### Install DSPy and OpenTelemetry Packages

Source: https://docs.orq.ai/docs/proxy/frameworks/dspy

Installs the core DSPy library, OpenTelemetry SDK, OTLP exporter, and the OpenInference DSPy instrumentation. Also installs the OpenAI provider package.

```bash
pip install dspy-ai opentelemetry-sdk opentelemetry-exporter-otlp
pip install openinference-instrumentation-dspy
pip install openai
```

--------------------------------

### Install Python SDKs

Source: https://docs.orq.ai/docs/experiments/build

Install the necessary Python packages for using the evaluatorq framework and orq-ai-sdk.

```bash
pip install orq-ai-sdk
pip install evaluatorq
```

--------------------------------

### Initialize Orq Client and Prospect System

Source: https://docs.orq.ai/docs/common-architecture/ai-agent

Sets up the Orq client with an API key and environment, then initializes the ProspectQualificationSystem.

```python
  # Initialize the system
  client = Orq(
      api_key=os.environ.get("ORQ_API_KEY", "__API_KEY__"),
      environment="production"
  )

  prospect_system = ProspectQualificationSystem(client)

  # Example prospect responses for the ingestion loop
  prospect_responses = [
      "Hi, I'm exploring AI solutions for our customer support team.",
      "We're TechCorp, a B2B SaaS company with about 200 employees in the healthcare tech space.",
      "I'm Sarah Johnson, VP of Customer Success. You can reach me at [email protected] or 555-0123.",
      "We're handling 1000+ support tickets daily and our team is overwhelmed. We need AI to handle tier-1 inquiries automatically and escalate complex issues to human agents.",
      "We're looking to implement within 3 months and have allocated $75,000 annually for this type of solution.",
      "Yes, I'm the final decision maker for customer success tools under $100k.",
      "We currently use Zendesk and have a team of 12 support agents. Our main pain point is response time - currently averaging 4 hours."
  ]

  # Run the complete workflow
  result = prospect_system.run_prospect_qualification(prospect_responses)
```

--------------------------------

### Set up Instructor Instrumentation

Source: https://docs.orq.ai/docs/proxy/frameworks/instructor

Configure the tracer provider and OTLP exporter, then instrument the Instructor client for automatic tracing. Ensure environment variables for endpoint and headers are set.

```python
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import os

# Configure tracer provider
tracer_provider = TracerProvider(
    resource=Resource({"service.name": "instructor-app"})
)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter(
    endpoint=f"{os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT')}/v1/traces",
    headers={"Authorization": os.getenv('OTEL_EXPORTER_OTLP_HEADERS').split('=', 1)[1]}
)

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Instrument Instructor
from openinference.instrumentation.instructor import InstructorInstrumentor

InstructorInstrumentor().instrument(tracer_provider=tracer_provider)
```

--------------------------------

### LangGraph Agent Example

Source: https://docs.orq.ai/docs/quickstarts/log-your-first-trace

This example demonstrates setting up a LangGraph agent with weather functionality and logging traces. Ensure you have the necessary dependencies installed.

```typescript
function weatherAgent(state: typeof MessagesAnnotation.State) {
            return llm.invoke(state.messages).then((response) => ({ messages: [response] }));
          }

          function route(state: typeof MessagesAnnotation.State) {
            const last = state.messages[state.messages.length - 1];
            const toolCalls = last.tool_calls;
            return toolCalls?.length ? 'tools' : '__end__';
          }

          const graph = new StateGraph(MessagesAnnotation)
            .addNode('weather_agent', weatherAgent)
            .addNode('tools', new ToolNode(tools))
            .addEdge(START, 'weather_agent')
            .addConditionalEdges('weather_agent', route)
            .addEdge('tools', 'weather_agent')
            .compile();

          const result = await graph.invoke({
            messages: [new HumanMessage('Weather in Tokyo?')],
          });
          console.log(result.messages[result.messages.length - 1].content);
```

--------------------------------

### Multi-Agent Crew Example with Orq.ai

Source: https://docs.orq.ai/docs/proxy/frameworks/crewai

An example of a multi-agent CrewAI setup using the Orq.ai AI Router. This demonstrates orchestrating multiple agents with specialized roles and tasks, including context passing between tasks.

```python
from crewai import Agent, Task, Crew, LLM
import os

llm = LLM(
    model="openai/gpt-4o",
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router",
)

researcher = Agent(
    role="Research Analyst",
    goal="Research topics and gather key facts",
    backstory="Expert at finding and summarizing information.",
    llm=llm,
)

writer = Agent(
    role="Content Writer",
    goal="Write clear, engaging content",
    backstory="Skilled at turning research into readable content.",
    llm=llm,
)

research_task = Task(
    description="Research the key benefits of renewable energy in 3 bullet points.",
    agent=researcher,
    expected_output="3 bullet points about renewable energy benefits.",
)

write_task = Task(
    description="Write a one-paragraph summary based on the research.",
    agent=writer,
    expected_output="A single paragraph summarizing renewable energy benefits.",
    context=[research_task],
)

crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task], tracing=False)
result = crew.kickoff()
print(result)
```

--------------------------------

### Orq and DeepEval Setup

Source: https://docs.orq.ai/docs/tutorials/evaluator-q

Initializes Orq client and checks for DeepEval availability. Sets up necessary API keys for Orq and OpenAI (required by DeepEval).

```python
import asyncio
from evaluatorq import evaluatorq, job, DataPoint, EvaluationResult
from orq_ai_sdk import Orq
import os

# ============================================ 
# CONFIGURATION
# ============================================ 
ORQ_API_KEY = os.getenv("ORQ_API_KEY", "")
if not ORQ_API_KEY:
    raise ValueError("ORQ_API_KEY environment variable must be set")

# ============================================ 
# CRITICAL: Set OpenAI API Key for DeepEval
# ============================================ 
# DeepEval uses OpenAI's API internally for evaluation
# You MUST set this before importing DeepEval
if not os.getenv("OPENAI_API_KEY"):
    print("CRITICAL: OPENAI_API_KEY not set!")
    print("Add this cell BEFORE running evaluation:")
    print("  import os")
    print('  os.environ["OPENAI_API_KEY"] = "sk-your-openai-key"')
    print()

# DeepEval library imports
try:
    from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric
    from deepeval.test_case import LLMTestCase
    DEEPEVAL_AVAILABLE = True
    print("✓ DeepEval loaded")
except ImportError:
    DEEPEVAL_AVAILABLE = False
    print("DeepEval not installed. Run: pip install deepeval")

# Initialize Orq client
orq_client = Orq(api_key=ORQ_API_KEY)

# Replace with your Orq LLM-as-a-judge Evaluator ID
# Get it from: https://my.orq.ai/project/evaluators/<YOUR_ID>
# Or via API: https://docs.orq.ai/reference/evaluators/get-all-evaluators
LLM_JUDGE_EVAL_ID = "$YOUR_LLM_AS_A_JUDGE_ID"
```

--------------------------------

### Install Orq AI SDK

Source: https://docs.orq.ai/docs/tutorials/chaining-deployments

Install the Orq AI SDK using pip. This is the first step to using Orq's capabilities.

```bash
!pip install orq-ai-sdk
```

--------------------------------

### Compare Two Prompt Strategies (CLI Example)

Source: https://docs.orq.ai/docs/experiments/overview

Example command to create an experiment comparing two prompt strategies on the 'customer-feedback' dataset. It includes auto-running the experiment and summarizing results.

```bash
Create an experiment using the "customer-feedback" dataset with two prompts: one focused on empathy and one on brevity. Run it and summarize the results.

```

--------------------------------

### Setup Observability and Verify Traces

Source: https://docs.orq.ai/docs/integrations/code-assistants/skills

Use this snippet to add Orq.ai tracing to an existing application and verify that traces are being generated. It initiates the setup and then checks the last hour of traces.

```bash
"Add orq.ai tracing to my app"                 → setup-observability
/orq:traces --last 1h                           # Verify traces are flowing
```

--------------------------------

### Custom Spans for Agent Operations

Source: https://docs.orq.ai/docs/proxy/frameworks/openai-agents

This example shows how to add custom spans to trace specific agent operations, such as the overall execution time. It requires similar setup to the function calling example, plus obtaining a tracer instance to create spans.

```Python
import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from orq_ai_sdk.openai_agents_instrumentation import OpenAIAgentsInstrumentor
from agents import Agent, Runner
from agents import trace as agent_trace

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://api.orq.ai/v2/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Bearer {os.environ['ORQ_API_KEY']}"

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

tracer = provider.get_tracer(__name__)

agent = Agent(
    name="Research Assistant",
    instructions="You are a research assistant specialized in data analysis.",
)

with agent_trace(workflow_name="Research-Workflow"):
    with tracer.start_as_current_span("agent-execution") as exec_span:
        result = Runner.run_sync(agent, "Analyze the trends in the uploaded dataset")
        exec_span.set_attribute("execution.status", "completed")
    print("Final output:", result.final_output)

provider.shutdown()
```

--------------------------------

### Create and Run an Experiment

Source: https://docs.orq.ai/docs/integrations/code-assistants/claude-desktop

This example demonstrates how to create an experiment with a specified name, dataset, and models, and then automatically run it. Claude will search for the dataset, create the experiment, configure task columns for the specified models, and execute them.

```prompt
Create an experiment called "Model Comparison Test" using my "customer-queries" dataset.
Configure it with GPT-5.2 and Claude Sonnet 4.6, then run it.
```

--------------------------------

### Basic LiveKit Agent with Tracing (Python)

Source: https://docs.orq.ai/docs/proxy/frameworks/livekit

A basic LiveKit agent example that includes OpenTelemetry tracing setup and connects to a room. Uses `AutoSubscribe.AUDIO_ONLY` for connection.

```python
import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from livekit.agents.telemetry import set_tracer_provider
from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli
from livekit.plugins import openai


def setup_tracing():
    exporter = OTLPSpanExporter(
        endpoint="https://api.orq.ai/v2/otel/v1/traces",
        headers={"Authorization": f"Bearer {os.environ['ORQ_API_KEY']}"},
    )
    provider = TracerProvider()
    provider.add_span_processor(BatchSpanProcessor(exporter))
    set_tracer_provider(provider)


async def entrypoint(ctx: JobContext):
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)

    assistant = openai.realtime.RealtimeModel(voice="alloy")
    agent = openai.realtime.RealtimeAgent(model=assistant)
    agent.start(ctx.room)


if __name__ == "__main__":
    setup_tracing()
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

--------------------------------

### Example Agent Instruction for Web Search

Source: https://docs.orq.ai/docs/agents/overview

This example shows how to instruct an agent to use the google_search tool. It specifies the tool's purpose, when to use it, and how to format queries.

```text
You are a research assistant. Your job is to find current information.

**Available Tools:**

1. **google_search** - Search the internet for information
   - Use this when you need current information or factual data
   - Provide clear search queries
   - Example: When asked "What are the latest AI developments?", call google_search with "latest AI developments 2025"


```

--------------------------------

### Example Web Search Agent Instructions

Source: https://docs.orq.ai/docs/agents/agent-studio

Illustrates how to instruct an agent to use the google_search tool, including its purpose and usage examples. This ensures the model knows when and how to invoke the tool.

```text
You are a research assistant. Your job is to find current information.

**Available Tools:**

1. **google_search** - Search the internet for information
   - Use this when you need current information or factual data
   - Provide clear search queries
   - Example: When asked "What are the latest AI developments?", call google_search with "latest AI developments 2025"

```

--------------------------------

### Intent Classification Prompt

Source: https://docs.orq.ai/docs/tutorials/intent-classification

Define the intents and provide examples for the model to learn from. This prompt guides the model to identify user intent based on predefined categories.

```bash
You are tasked with identifying the intent behind user inputs based on the following intents:
'PlayMusic', 'AddToPlaylist', 'RateBook', 'Greetings', 'SearchScreeningEvent', 'BookRestaurant', 'GetWeather', 'Book Meeting', 'SearchCreativeWork', 'Cancellation', 'Affirmation', 'excitment'.

Here are some examples: 

Input: "Hey there, how are you doing?"
Intent: Greetings

Input: "Play the album Abbey Road by The Beatles."
Intent: PlayMusic

Input: "Add this song to my workout playlist."
Intent: AddToPlaylist

Input: "This book deserves a solid five-star rating."
Intent: RateBook

ONLY OUTPUT THE LABEL WITHOUT ''

here is the input that needs intent classification: {{text}} 
```

--------------------------------

### Using orq:current_date tool

Source: https://docs.orq.ai/docs/agents/responses-api

Example of calling the orq:current_date tool via the API to get the current time. Ensure your ORQ_API_KEY is set as an environment variable.

```bash
curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "What time is it?",
    "tools": [{ "type": "orq:current_date" }]
  }'
```

--------------------------------

### Main Evaluation Runner Setup

Source: https://docs.orq.ai/docs/tutorials/evaluator-q

Sets up and prints configuration details for running agent evaluations. It checks for required API keys and library availability.

```python
async def main():
        print("=" * 70)
        print("Comparing LangChain vs Orq Native Agent")
        print("Both agents: GPT-4o | Cloud Engineering Assistant")
        print("=" * 70)
        print()

        print("Configuration:")
        print(f
```

--------------------------------

### Single Tool Agent with LangGraph (Python)

Source: https://docs.orq.ai/docs/proxy/frameworks/langgraph

Example of creating a LangGraph agent with a single tool (get_weather) using the Orq AI SDK. Ensure setup() is called before graph invocation.

```Python
from orq_ai_sdk.langchain import setup

setup()

from typing import Annotated, Literal, TypedDict
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain.tools import tool
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode

class State(TypedDict):
    messages: Annotated[list, add_messages]

@tool
def get_weather(location: str) -> str:
    """Get weather for a location."""
    data = {"tokyo": "Sunny, 22°C", "paris": "Cloudy, 15°C", "new york": "Rainy, 18°C"}
    return data.get(location.lower(), f"No data for {location}")

tools = [get_weather]
llm   = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

def weather_agent(state: State):
    return {"messages": [llm.invoke(state["messages")]}

def route(state: State) -> Literal["tools", "__end__"]:
    last = state["messages"][-1]
    return "tools" if hasattr(last, "tool_calls") and last.tool_calls else "__end__"

graph = StateGraph(State)
graph.add_node("weather_agent", weather_agent)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "weather_agent")
graph.add_conditional_edges("weather_agent", route)
graph.add_edge("tools", "weather_agent")

app = graph.compile()
result = app.invoke({"messages": [HumanMessage(content="Weather in Tokyo?")]})
print(result["messages"][-1].content)
```

--------------------------------

### Install Orq.ai SDK and Langchain Libraries

Source: https://docs.orq.ai/docs/proxy/frameworks/langchain

Install the necessary Python or Node.js packages for Orq.ai and Langchain integration.

```bash
pip install orq-ai-sdk langchain-core langchain-openai langgraph
```

```bash
npm install @orq-ai/node @langchain/core @langchain/langgraph @langchain/openai
```

--------------------------------

### TypeScript: Extract JSON from Chat Completions using Zod

Source: https://docs.orq.ai/docs/proxy/structured-outputs

This TypeScript example demonstrates how to get structured JSON from chat completions using the OpenAI SDK and Zod for schema definition.

```typescript
import OpenAI from "openai";
import { z } from "zod";
import { zodResponseFormat } from "openai/helpers/zod";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

const UserInfoSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string(),
  occupation: z.string(),
});

const response = await client.chat.completions.parse({
  model: "openai/gpt-4o",
  messages: [
    {
      role: "user",
      content: "Extract user information from: John Doe, 30 years old, [email protected], Software Engineer",
    },
  ],
  response_format: zodResponseFormat(UserInfoSchema, "user_info"),
});

const user = response.choices[0].message.parsed;
console.log(`Name: ${user.name}`);
console.log(`Occupation: ${user.occupation}`);

```

--------------------------------

### Basic DSPy Question Answering

Source: https://docs.orq.ai/docs/proxy/frameworks/dspy

A basic example demonstrating how to use DSPy for question answering after configuring the AI Router. It defines a simple signature and uses dspy.Predict to get an answer.

```python
import dspy
import os

lm = dspy.LM(
    "openai/openai/gpt-4o",
    api_key=os.getenv("ORQ_API_KEY"),
    api_base="https://api.orq.ai/v3/router",
)
dspy.configure(lm=lm)

class BasicQA(dspy.Signature):
    """Answer questions with short, accurate responses."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()

qa = dspy.Predict(BasicQA)
result = qa(question="What is the capital of France?")
print(result.answer)
```

--------------------------------

### Basic ReActAgent Example with Orq.ai Router

Source: https://docs.orq.ai/docs/proxy/frameworks/llama-agents

Demonstrates creating a `ReActAgent` that uses a custom tool and is configured with Orq.ai's AI Router. This example shows how to define a tool, initialize the agent with the configured LLM, and run a query.

```python
import asyncio
from llama_index.core.agent.workflow import ReActAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai_like import OpenAILike
import os

# Configure LLM with Orq.ai AI Router
llm = OpenAILike(
    model="gpt-4o",
    api_key=os.getenv("ORQ_API_KEY"),
    api_base="https://api.orq.ai/v3/router",
    is_chat_model=True,
)

# Define a tool
def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"The weather in {location} is sunny and 72°F"

# Create agent
agent = ReActAgent(
    tools=[FunctionTool.from_defaults(get_weather)],
    llm=llm,
)

async def main():
    response = await agent.run("What's the weather in San Francisco?")
    print(response)

asyncio.run(main())
```

--------------------------------

### Model Selection Example (Python)

Source: https://docs.orq.ai/docs/proxy/frameworks/openai-agents

Demonstrates how to configure agents to use different models available through Orq.ai, such as Claude and Gemini.

```python
from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_client, set_tracing_disabled
import os

# Configure client
client = AsyncOpenAI(
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)
set_tracing_disabled(True)
set_default_openai_client(client)

# Use Claude
claude_agent = Agent(
    name="Claude Assistant",
    model="claude-sonnet-4-5-20250929",
    instructions="You are a helpful assistant."
)

# Use Gemini
gemini_agent = Agent(
    name="Gemini Assistant",
    model="gemini-2.5-flash",
    instructions="You are a helpful assistant."
)

```

--------------------------------

### Basic Pydantic AI Agent with Orq.ai Router

Source: https://docs.orq.ai/docs/proxy/frameworks/pydantic-ai

Create and run a simple Pydantic AI agent that uses the Orq.ai AI Router. This example demonstrates the core setup for agent execution.

```python
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
import os

# Configure client with Orq.ai AI Router
client = AsyncOpenAI(
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("gpt-4o", provider=provider)

# Create agent
agent = Agent(
    model=model,
    system_prompt="You are a helpful assistant."
)

# Run the agent
result = agent.run_sync("Explain quantum computing in simple terms")
print(result.output)
```

--------------------------------

### LangGraph Workflow with Tool Calls (TypeScript)

Source: https://docs.orq.ai/docs/proxy/frameworks/langgraph

Illustrates building a LangGraph in TypeScript, defining tools, an assistant agent, and routing logic. This example uses Orq AI's setup for LangChain.

```typescript
import { HumanMessage } from '@langchain/core/messages';
import { tool } from '@langchain/core/tools';
import { StateGraph, START, MessagesAnnotation } from '@langchain/langgraph';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { ChatOpenAI } from '@langchain/openai';
import { setup } from '@orq-ai/node/langchain';
import { z } from 'zod';

setup();

const calculator = tool(
  async ({ expression }: { expression: string }) => {
    try {
      return String(Function(`"use strict"; return (${expression})`)()); // demo only — use a safe parser in production
    } catch {
      return 'Error';
    }
  },
  {
    name: 'calculator',
    description: 'Evaluate a math expression.',
    schema: z.object({ expression: z.string() }),
  },
);

const getTime = tool(
  async () => new Date().toLocaleTimeString('en-GB', { hour12: false }),
  {
    name: 'get_time',
    description: 'Get the current time.',
    schema: z.object({}),
  },
);

const tools = [calculator, getTime];
const llm = new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }).bindTools(tools);

function assistantAgent(state: typeof MessagesAnnotation.State) {
  return llm.invoke(state.messages).then((response) => ({ messages: [response] }));
}

function route(state: typeof MessagesAnnotation.State) {
  const last = state.messages[state.messages.length - 1];
  const toolCalls = last.tool_calls;
  return toolCalls?.length ? 'tools' : '__end__';
}

const graph = new StateGraph(MessagesAnnotation)
  .addNode('assistant_agent', assistantAgent)
  .addNode('tools', new ToolNode(tools))
  .addEdge(START, 'assistant_agent')
  .addConditionalEdges('assistant_agent', route)
  .addEdge('tools', 'assistant_agent')
  .compile();

const result = await graph.invoke({
  messages: [new HumanMessage('What is 25 * 4? Also what time is it?')],
});
console.log(result.messages[result.messages.length - 1].content);
```

--------------------------------

### Basic Agno Agent with Observability

Source: https://docs.orq.ai/docs/proxy/frameworks/agno

Demonstrates creating an Agno agent and sending a response, with observability configured. The OTEL setup must precede agent instantiation.

```python
import os
from opentelemetry import trace as trace_api
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.orq.ai/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['ORQ_API_KEY']}"},
)
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
trace_api.set_tracer_provider(tracer_provider)

from openinference.instrumentation.agno import AgnoInstrumentor
AgnoInstrumentor().instrument()

from agno.agent import Agent
from agno.models.openai.like import OpenAILike

agent = Agent(
    name="orq-demo",
    model=OpenAILike(
        id="openai/gpt-4o-mini",
        api_key=os.getenv("ORQ_API_KEY"),
        base_url="https://api.orq.ai/v3/router",
    ),
    markdown=True,
)
agent.print_response("Summarize the latest AI news.")
```

--------------------------------

### Multiple Tools Agent with LangGraph (Python)

Source: https://docs.orq.ai/docs/proxy/frameworks/langgraph

Example of creating a LangGraph agent with multiple tools (calculator, get_time) using the Orq AI SDK. Ensure setup() is called before graph invocation.

```Python
from orq_ai_sdk.langchain import setup

setup()

from datetime import datetime
from typing import Annotated, Literal, TypedDict
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain.tools import tool
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode

class State(TypedDict):
    messages: Annotated[list, add_messages]

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression."""
    try:
        return str(eval(expression))
    except Exception:
        return "Error"

@tool
def get_time() -> str:
    """Get the current time."""
    return datetime.now().strftime("%H:%M:%S")

tools = [calculator, get_time]
llm   = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

def assistant_agent(state: State):
    return {"messages": [llm.invoke(state["messages")]}

def route(state: State) -> Literal["tools", "__end__"]:
    last = state["messages"][-1]

```

--------------------------------

### Configure Orq.ai Model and Knowledge Base

Source: https://docs.orq.ai/docs/tutorials/lovable-integration

This example shows how to set the system prompt to use a specific knowledge base and configure primary and fallback models.

```markdown
Replace `{{orq_technical_docs}}` with the name of the knowledge base you uploaded.
```

--------------------------------

### Initialize and Ask Question with RAG SDK

Source: https://docs.orq.ai/docs/common-architecture/simple-rag

Demonstrates how to initialize a RAG system and ask a question. Includes handling of the answer and sources from the response.

```javascript
const rag = new RAG(client, "simpleRAG");
const result = await rag.askQuestion("What is our company return policy?");

console.log(`Answer: ${result.answer}`);
if (result.sources.length > 0) {
    console.log("\nSources:");
    result.sources.forEach(source => {
        console.log(`- ${source.source}: ${source.content.substring(0, 100)}...`);
    });
}
```

--------------------------------

### Single Tool Agent with LangGraph (Node.js)

Source: https://docs.orq.ai/docs/proxy/frameworks/langgraph

Example of creating a LangGraph agent with a single tool (get_weather) using the Orq AI SDK in Node.js. Ensure setup() is called before graph invocation.

```typescript
import { HumanMessage } from '@langchain/core/messages';
import { tool } from '@langchain/core/tools';
import { StateGraph, START, MessagesAnnotation } from '@langchain/langgraph';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { ChatOpenAI } from '@langchain/openai';
import { setup } from '@orq-ai/node/langchain';
import { z } from 'zod';

setup();

const getWeather = tool(
    async ({ location }: { location: string }) => {
      const data: Record<string, string> = {
        tokyo: 'Sunny, 22°C',
        paris: 'Cloudy, 15°C',
        'new york': 'Rainy, 18°C',
      };
      return data[location.toLowerCase()] ?? `No data for ${location}`;
    },
    {
      name: 'get_weather',
      description: 'Get weather for a location.',
      schema: z.object({ location: z.string() }),
    },
);

const tools = [getWeather];
const llm = new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }).bindTools(tools);

function weatherAgent(state: typeof MessagesAnnotation.State) {
    return llm.invoke(state.messages).then((response) => ({ messages: [response] }));
}

function route(state: typeof MessagesAnnotation.State) {
    const last = state.messages[state.messages.length - 1];
    const toolCalls = last.tool_calls;
    return toolCalls?.length ? 'tools' : '__end__';
}

const graph = new StateGraph(MessagesAnnotation)
    .addNode('weather_agent', weatherAgent)
    .addNode('tools', new ToolNode(tools))
    .addEdge(START, 'weather_agent')
    .addConditionalEdges('weather_agent', route)
    .addEdge('tools', 'weather_agent')
    .compile();

const result = await graph.invoke({
    messages: [new HumanMessage('Weather in Tokyo?')],
});
console.log(result.messages[result.messages.length - 1].content);
```

--------------------------------

### Create Experiment from Existing Dataset (CLI Example)

Source: https://docs.orq.ai/docs/experiments/overview

Example command to create an experiment comparing two models (GPT-5.2 and Claude Sonnet 4.6) using a specified dataset ('user-queries'). The experiment is set to auto-run.

```bash
Create an experiment comparing GPT-5.2 and Claude Sonnet 4.6 using the "user-queries" dataset

```

--------------------------------

### Call Agent with Memory Store (TypeScript)

Source: https://docs.orq.ai/docs/agents/run

This TypeScript example shows how to use the Orq Node.js SDK to interact with an agent that has memory. Ensure the `@orq-ai/node` package is installed and your API key is available in the environment.

```typescript
import { Orq } from '@orq-ai/node';

const orq = new Orq({ apiKey: process.env['ORQ_API_KEY'] ?? '' });

const response = await orq.agents.responses.create({
  memory: {
    entityId: 'customer_456',
  },
  message: {
    role: 'user',
    parts: [
      {
        kind: 'text',
        text: 'Do you remember what is my name?',
      },
    ],
  },
}, 'agent-memories');

console.log(response);
```

--------------------------------

### DeepEval Faithfulness Evaluation Setup

Source: https://docs.orq.ai/docs/tutorials/evaluator-q

Configures and runs DeepEval's Faithfulness metric for evaluating agent responses against provided context. It checks for necessary API keys and installations, and handles potential errors during evaluation.

```python
async def deepeval_faithfulness_evaluator(params):
    """Uses DeepEval's faithfulness metric (requires OPENAI_API_KEY)."""
    if not DEEPEVAL_AVAILABLE:
        return EvaluationResult(value=0.0, explanation="DeepEval not installed")

    if not os.getenv("OPENAI_API_KEY"):
        return EvaluationResult(value=0.0, explanation="OPENAI_API_KEY not set")

    output = params["output"]

    if output.get("error"):
        return EvaluationResult(value=0.0, explanation=f"{output['agent']}: Job error")

    query = output.get("query", "").strip()
    response = output.get("response", "").strip()
    context = output.get("context", "").strip()

    if not response or not context:
        return EvaluationResult(value=0.0, explanation="Missing response or context")

    try:
        # Create test case
        test_case = LLMTestCase(
            input=query,
            actual_output=response,
            retrieval_context=[context],
        )

        # Initialize metric
        metric = FaithfulnessMetric(
            threshold=0.5,
            model="gpt-4o-mini",  # Use gpt-4o-mini to save costs
            include_reason=False,
        )

        # Measure (synchronous call in thread)
        def measure_sync():
            metric.measure(test_case)
            return float(metric.score) if metric.score is not not None else 0.0

        score = await asyncio.to_thread(measure_sync)

        return EvaluationResult(
            value=score,
            explanation=f"{output['agent']}: Faithfulness {score:.2f}"
        )

    except Exception as e:
        print(f"✗ DeepEval error: {e}")
```

--------------------------------

### TypeScript PDF Input (Responses API)

Source: https://docs.orq.ai/docs/proxy/multimodal

This TypeScript example shows how to read a PDF file, base64 encode it, and send it for analysis using the Responses API. Ensure you have the 'openai' package installed and your API key configured.

```typescript
import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

const pdfBase64 = fs.readFileSync("document.pdf").toString("base64");

const response = await client.responses.create({
  model: "openai/gpt-4o",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "Please analyze this PDF document and provide a summary" },
        {
          type: "input_file",
          filename: "document.pdf",
          file_data: `data:application/pdf;base64,${pdfBase64}`,
        },
      ],
    },
  ],
});

console.log(response.output_text);
```

--------------------------------

### Create a Deployment

Source: https://docs.orq.ai/docs/deployments/overview

Use the `create_deployment` function to set up a new customer support deployment. Specify the key, project path, model, and system prompt. It's recommended to use `list_models` first to find valid model IDs.

```Orq MCP
Create a customer support deployment called "support-bot" in the Default/Deployments project. Use GPT-4o with a professional, concise system prompt.

```

--------------------------------

### Python Request to Google Gemini via AI Router (OpenAI SDK)

Source: https://docs.orq.ai/docs/integrations/providers/google-ai

Integrate Google Gemini models using the OpenAI SDK in Python. This example shows how to get a standard response. Ensure your ORQ_API_KEY is set.

```python
from openai import OpenAI
import os

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

response = client.responses.create(
    model="google-ai/gemini-2.5-pro",
    input="Explain quantum computing in simple terms",
)

print(response.output_text);
```

--------------------------------

### Create a Deployment using MCP

Source: https://docs.orq.ai/docs/deployments/creating

Use the `create_deployment` command to set up a new deployment. Specify the key, project path, model, and system prompt. You may need to use `list_models` to find valid model IDs.

```prompt
Create a customer support deployment called "support-bot" in the Default/Deployments project. Use GPT-4o with a professional, concise system prompt.
```

--------------------------------

### Install Orq.ai SDK

Source: https://docs.orq.ai/docs/tutorials/multilingual-faq-bot

Install the necessary Python package to use the Orq SDK and manage your knowledge base.

```bash
pip install orq-ai-sdk 
```

--------------------------------

### TypeScript Request to Google Gemini via AI Router (OpenAI SDK)

Source: https://docs.orq.ai/docs/integrations/providers/google-ai

Integrate Google Gemini models using the OpenAI SDK in TypeScript. This example shows how to get a standard response. Ensure your ORQ_API_KEY is set.

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

const response = await client.responses.create({
  model: "google-ai/gemini-2.5-pro",
  input: "Explain quantum computing in simple terms",
});

console.log(response.output_text);
```
Tokens:
Raw