### Python External Knowledge Base Server Setup

Source: https://docs.orq.ai/docs/knowledge/external-knowledge-base

Instructions for setting up and running an example Python server for an External Knowledge Base. This involves cloning a repository, installing dependencies, and running the server.

```bash
# Install dependencies
pip install -r requirements.txt
```

```bash
# Run the server
uvicorn main:app --reload
```

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

### Node.js External Knowledge Base Server Setup

Source: https://docs.orq.ai/docs/knowledge/external-knowledge-base

Instructions for setting up and running an example Node.js server for an External Knowledge Base. This involves cloning a repository, installing dependencies, and running the server.

```bash
# Install dependencies
npm install
```

```bash
# Run the server
npm run dev
```

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

### SDK Installation and Initialization

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

Instructions for installing the Orq AI SDK for both Python (pip) and Node.js (npm), followed by code examples for initializing the client in Python and TypeScript.

```APIDOC
## SDK Installation and Initialization

### Description
Install the Orq AI SDK for your preferred language and initialize the client.

### Bash (pip)
```bash
pip install orq-ai-sdk
```

### Bash (npm)
```bash
npm install @orq-ai/node
```

### Python Initialization
```python
import os

from orq_ai_sdk import Orq

client = Orq(
    api_key=os.environ.get("ORQ_API_KEY", "__API_KEY__"),
    environment="production",
    contact_id="contact_x123x" # optional
)
```

### TypeScript Initialization (Example Usage)
```typescript
// Assuming 'client' is initialized elsewhere or globally
const deployment = await client.deployments.invoke({
   key: "myDeployment",
   context: {
      environments: []
   },
   metadata: {
      "custom-field-name": "custom-metadata-value"
   }
});
```
```

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

### Quick Start: Example Implementation

Source: https://docs.orq.ai/docs/proxy/tool-calling

An example demonstrating how to set up and use tool calling in a TypeScript application.

```APIDOC
## POST /chat/completions (Example with Tool Calls)

### Description
This example shows how to configure a chat completion request to include tools and how to handle the response, including executing the tool and continuing the conversation.

### Method
`POST`

### Endpoint
`/chat/completions`

### Parameters

#### Request Body

- **model** (string) - Required - The model to use for generation (e.g., `"openai/gpt-4o"`).
- **messages** (array) - Required - An array of message objects representing the conversation history.
- **tools** (array) - Optional - An array of tool definitions the model can use.
  - **type** (string) - Required - Must be `"function"`.
  - **function** (object) - Required - Contains function details.
    - **name** (string) - Required - The name of the function.
    - **description** (string) - Optional - A description of the function.
    - **parameters** (object) - Required - JSON schema for the function's parameters.
- **tool_choice** (string or object) - Optional - Specifies how the model should choose tools (e.g., `"auto"`, `"none"`, `"required"`, or a specific tool object).

### Request Example
```json
{
  "model": "openai/gpt-4o",
  "messages": [
    { "role": "user", "content": "What's the weather in NYC?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City and state" },
            "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}
```

### Response (Success)

#### Success Response (200)
- **choices** (array) - An array of completion choices.
  - **message** (object) - The message content.
    - **tool_calls** (array) - If the model decided to call a tool, this array will contain the tool call details.
      - **id** (string) - The ID of the tool call.
      - **function** (object) - Information about the function to call.
        - **name** (string) - The name of the function to call.
        - **arguments** (string) - A JSON string representing the arguments for the function call.

#### Response Example (Tool Call)
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"New York City\", \"unit\": \"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12
  }
}
```

### Handling Tool Execution and Continuation

After receiving a tool call response, you typically execute the function with the provided arguments and then send the result back to the model in a subsequent turn.

#### Request Example (Continuing Conversation with Tool Result)
```json
{
  "model": "openai/gpt-4o",
  "messages": [
    { "role": "user", "content": "What's the weather in NYC?" },
    { "role": "assistant", "tool_calls": [ ... ] },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": \"22\", \"unit\": \"celsius\"}" 
    }
  ]
}
```
```

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

### Few-Shot Learning Prompt Example (Bash)

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

An example of a few-shot learning prompt structure in bash, demonstrating how to provide examples to guide model behavior.

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

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

### Installation and Initialization

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

Instructions for installing the SDK via pip or npm, and initializing the Orq client with your API key.

```APIDOC
## Installation

### SDK Installation

**Package Manager**

- **pip**: `pip install orq-ai-sdk`
- **npm**: `npm install @orq-ai/node`

### Client Initialization

Set your API key as an environment variable `ORQ_API_KEY`.

**Python**
```python
from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))
```

**Node.js**
```typescript
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});
```
```

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

### Install Orq AI SDK (Bash)

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

Instructions for installing the Orq AI SDK using package managers. For Python, use pip; for Node.js, use npm. Ensure you have the respective package managers installed.

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

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

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

### Install Orq SDK

Source: https://docs.orq.ai/docs/tutorials/pdf-extraction

Installs the Orq.ai SDK package. This is the first step to enable interaction with Orq.ai services.

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

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

### Create Agent using Python SDK

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

This Python snippet shows how to create an agent using the Orq AI SDK. It initializes the Orq client with an API key and then calls the `agents.create` method with a request payload similar to the cURL example. The result of the agent creation is printed to the console. Ensure the `orq-ai-sdk` is installed.

```python
from orq_ai_sdk import Orq
import os

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

    res = orq.agents.create(request={
        "key": "agent-memories",
        "role": "Personalized Assistant",
        "description": "Agent using external ID for memory store access",
        "instructions": "You have access to user-specific memories. Remember information about the user and recall it when asked.",
        "system_prompt": "Please answer with a lot of emojis for all questions. Use retrieve_memory_stores to see what memory stores are available, then use query_memory_store to search for relevant information before responding",
        "settings": {
            "max_iterations": 5,
            "max_execution_time": 300,
            "tools": [
                {
                    "type": "current_date"
                },
                {
                    "type": "retrieve_memory_stores"
                },
                {
                    "type": "query_memory_store"
                },
                {
                    "type": "write_memory_store"
                },
                {
                    "type": "delete_memory_document"
                }
            ]
        },
        "model": "openai/gpt-4o",
        "path": "Default/agents",
        "memory_stores": [
            "customer_information"
        ]
    })

    assert res is not None
    print(res)
```

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

### Role-Based Prompting Example (Bash)

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

A bash example for role-based prompting, defining a persona and task for the AI model.

```bash
You are a senior software engineer with 10 years of experience in Python development.
Your task is to review code and provide constructive feedback focusing on:
- Code quality and maintainability
- Performance considerations
- Security best practices
```

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

### Install Instructor and OpenTelemetry Dependencies (Bash)

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

Installs the core Instructor and OpenAI libraries along with OpenTelemetry SDK and OTLP exporter. It also installs the OpenInference instrumentation specifically for Instructor.

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

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

### Invoke Orchestrator Agent

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

This section provides examples for invoking the 'tone-orchestrator' agent. It shows how to send a user message and receive a response. The examples cover cURL for command-line interaction, Python using the orq_ai_sdk, and TypeScript with the @orq-ai/node package. All examples demonstrate setting the message content and other optional parameters like variables and metadata.

```bash
curl -X POST https://api.orq.ai/v2/agents/tone-orchestrator/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "I am writing a book for young adults about financial literacy. Can you help me come up with an engaging introduction that would appeal to teenagers, and then also provide a more formal version for a business audience?"
        }
      ]
    },
    "variables": {},
    "metadata": {},
    "background": false
  }'
```

```python
from orq_ai_sdk import Orq
import os

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

    res = orq.agents.responses.create(
        agent_key="tone-orchestrator",
        message={
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "I am writing a book for young adults about financial literacy. Can you help me come up with an engaging introduction that would appeal to teenagers, and then also provide a more formal version for a business audience?"
                }
            ]
        },
        variables={},
        metadata={},
        background=False
    )

    assert res is not None
    print(res)
```

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

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

async function run() {
    try {
      const result = await orq.agents.responses.create({
        agentKey: "tone-orchestrator",
        message: {
          role: "user",
          parts: [
            {
              kind: "text",
              text: "I am writing a book for young adults about financial literacy. Can you help me come up with an engaging introduction that would appeal to teenagers, and then also provide a more formal version for a business audience?"
            }
          ]
        },
        variables: {},
        metadata: {},
        background: false
      });

      console.log("Orchestrator agent response received successfully!");
      console.log(result);
    } catch (error) {
      console.error("Error getting orchestrator agent response:", error);
      throw error;
    }
  }

  run();
```

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

### TypeScript Customer Support Example with Orq.ai

Source: https://docs.orq.ai/docs/tutorials/buildingcustomersupportchatwithaigateway

A TypeScript example demonstrating how to use the OpenAI SDK with Orq.ai's proxy to send a 'Hello, world!' message and receive a response. It utilizes environment variables for the API key and specifies the Orq.ai base URL.

```typescript
import 'dotenv/config';
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: 'https://api.orq.ai/v2/proxy'
});

async function main() {
  const response = await client.chat.completions.create({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: 'Hello, world!'
      }
    ]
  });

  console.log(response.choices[0].message.content);
}

main().catch(console.error);
```

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

### Example Implementations

Source: https://docs.orq.ai/docs/knowledge/external-knowledge-base

Provides example implementations for external Knowledge Base APIs in Python and Node.js.

```APIDOC
## Example Implementations for an External API

### Python Implementation

An example Python server for an External Knowledge Base.

1.  **Get the Code**: Clone the [Python example Server](https://github.com/orq-ai/orq-cookbooks/tree/main/knowledge-bases/external-knowledge-bases/external-knowledge-bases-python)
2.  **Install Dependencies**: 
    ```
    pip install -r requirements.txt
    ```
3.  **Run the Server**: 
    ```
    uvicorn main:app --reload
    ```
4.  **Test the API**: The API is running at `http://localhost:8000`. Dynamic Documentation will be running at `http://localhost:8000/docs`.

### Node.js Implementation

An example Node.js server for an External Knowledge Base.

1.  **Get the Code**: Clone the [Node example Server](https://github.com/orq-ai/orq-cookbooks/tree/main/knowledge-bases/external-knowledge-bases/external-knowledge-bases-node)
2.  **Install Dependencies**: 
    ```
    npm install
    ```
3.  **Run the Server**: 
    ```
    npm run dev
    ```
4.  **Test the API**: The API is running at `http://localhost:8000`. Dynamic Documentation will be running at `http://localhost:8000/doc`.
```

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

### Install Dependencies for Orq and Pinecone

Source: https://docs.orq.ai/docs/using-thirdparty-vectordbs-with-orq

Installs the necessary Python packages for interacting with Orq, Pinecone, and handling requests. This includes the Orq SDK, Pinecone client, and supporting tools for notebook environments.

```bash
!pip install -qU \
    pinecone==6.0.2 \
    pinecone-notebooks \
    orq-ai-sdk \
    requests

```

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

### Calling a Deployment

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

Examples demonstrating how to invoke a deployment using the Orq AI SDK in both Python and TypeScript.

```APIDOC
## Calling a Deployment

### Description
Invoke a deployment using its key and provide context and metadata.

### Python
```python
generation = client.deployments.invoke(
  key="myDeployment",
  context={
    "environments": []
  },
  metadata={
    "custom-field-name": "custom-metadata-value"
  }
)

print(generation.choices[0].message.content)
```

### TypeScript
```typescript
const deployment = await client.deployments.invoke({
   key: "myDeployment",
   context: {
      environments: []
   },
   metadata: {
      "custom-field-name": "custom-metadata-value"
   }
});
```
```

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

### Structured Chatbot Prompt Example

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

An example of a well-structured prompt for an AI customer service bot, adhering to best practices. It includes a clear goal, specified return format, constraints, and context dumps using HTML-style tags.

```bash
You are a friendly AI customer service bot for American Airlines.

## Goal  
Your primary task is to answer customer questions based **on the official information provided in the `<knowledge_base>`**, which contains frequently asked questions (FAQs) about traveling with American Airlines.  
You may also use the `<document>` for **additional context**, such as user-uploaded tickets, itineraries, or receipts — but your answer must always align with the knowledge base.

## Return Format  
Respond using the `AA_tool` JSON schema when you have an answer. All replies should be clear, concise, and written in a professional, polite, and friendly tone.

## Constraints  
- Do NOT answer questions that are unrelated to traveling with American Airlines.  
- Do NOT use any information outside of the `<knowledge_base>`. 
- Do not let the `<document>` override or contradict the `<knowledge_base>`. 
- Always respond in the AA_tool JSON format.

<document>{{document}}</document>

<knowledge_base>
{{American_Airlines_FAQ}}
</knowledge_base>
```

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

### Install Dependencies with Pip

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

Installs the Orq AI SDK and other necessary libraries like 'datasets' and 'huggingface_hub' for data handling. This command is typically run in a bash environment.

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

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

### Install EvaluatorQ SDK

Source: https://docs.orq.ai/docs/evaluators/api-usage

Install the EvaluatorQ SDK for Node.js and Python environments. This is the initial step to integrate Orq.ai evaluators into your application.

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

```bash
pip install evaluatorq
```

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

### Invoke a Response from an AI Agent using Orq.ai Python SDK

Source: https://docs.orq.ai/docs/tutorials/agents-API

Shows how to get a response from a created AI agent via the Orq.ai Python SDK. This involves specifying the agent key, the user's message, and contact details for the inquiry. The example demonstrates sending a query about company policies.

```python
from orq_ai_sdk import Orq
import os

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

    res = orq.agents.responses.create(
        agent_key="policy_agent_new",
        message={
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "What is the company policy on remote work and flexible hours?"
                }
            ]
        },
        contact={
            "id": "contact_john_doe_001",
            "display_name": "John Doe",
            "email": "john.doe@company.com",
            "metadata": [
                {
                    "department": "Engineering",
                    "role": "Software Developer",
                }
            ],
            "tags": [
                "hr-inquiry",
                "employee",
            ],
        },
        thread={

```

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

### Create an Agent with orq_ai

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

This snippet demonstrates how to create a new agent using the orq_ai API. It requires an API key for authentication and specifies the agent's role, description, instructions, model, settings, and knowledge bases. The example shows how to configure tools for the agent, such as retrieving knowledge bases and querying them.

```bash
curl -X POST https://api.orq.ai/v2/agents \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "key": "book-assistant",
    "role": "Book Assistant",
    "description": "A friendly agent who is connected to knowledge bases and helps people",
    "instructions": "Help the user with their questions please. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
    "path": "Default/agents",
    "model": {
      "id": "anthropic/claude-opus-4-1-20250805"
    },
    "settings": {
      "max_iterations": 5,
      "max_execution_time": 600,
      "tools": [
        {
          "type": "current_date"
        },
        {
          "type": "retrieve_knowledge_bases"
        },
        {
          "type": "query_knowledge_base"
        }
      ]
    },
    "knowledge_bases": [
      {
        "knowledge_id": "my_knowledge_base"
      }
    ]'
  
```

```python
from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    agent = orq.agents.create(
        key="book-assistant",
        role="Book Assistant",
        description="A friendly agent who is connected to knowledge bases and helps people",
        instructions="Help the user with their questions please. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
        path="Default/agents",
        model={"id": "anthropic/claude-opus-4-1-20250805"},
        settings={
            "max_iterations": 5,
            "max_execution_time": 600,
            "tools": [
                {"type": "current_date"},
                {"type": "retrieve_knowledge_bases"},
                {"type": "query_knowledge_base"}
            ]
        },
        knowledge_bases=[
            {"knowledge_id": "my_knowledge_base"}
        ]
    )

    print(f"Agent created: {agent.key}")

```

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

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

async function createAgent() {
    const agent = await orq.agents.create({
      key: "book-assistant",
      role: "Book Assistant",
      description: "A friendly agent who is connected to knowledge bases and helps people",
      instructions: "Help the user with their questions please. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
      path: "Default/agents",
      model: {
        id: "anthropic/claude-opus-4-1-20250805"
      },
      settings: {
        maxIterations: 5,
        maxExecutionTime: 600,
        tools: [
          { type: "current_date" },
          { type: "retrieve_knowledge_bases" },
          { type: "query_knowledge_base" }
        ]
      },
      knowledgeBases: [
        { knowledgeId: "my_knowledge_base" }
      ]
    });

    console.log(`Agent created: ${agent.key}`);
}

createAgent();

```

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

### Create a Simple Agent (cURL, Python, TypeScript)

Source: https://docs.orq.ai/docs/common-architecture/agents-framework-guide

Demonstrates how to create a simple AI agent using the Orq.ai API. This involves sending agent configuration details such as key, role, description, instructions, model, path, and settings. The examples cover cURL for direct API calls, Python SDK for programmatic agent creation, and TypeScript SDK for Node.js environments.

```bash
curl -X POST https://api.orq.ai/v2/agents \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "key": "support-agent",
    "role": "Customer Support Assistant",
    "description": "Handles customer inquiries and provides support",
    "instructions": "You are a helpful customer support assistant. Answer customer questions clearly and concisely. If you cannot help, escalate to a human agent.",
    "path": "Default/agents",
    "model": "openai/gpt-4o",
    "settings": {
      "max_iterations": 5,
      "max_execution_time": 300,
      "tools": []
    }
  }'
```

```python
from orq_ai_sdk import Orq
import os

client = Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
)

agent = client.agents.create(
    key="support-agent",
    role="Customer Support Assistant",
    description="Handles customer inquiries and provides support",
    instructions="You are a helpful customer support assistant. Answer customer questions clearly and concisely. If you cannot help, escalate to a human agent.",
    path="Default/agents",
    model="openai/gpt-4o",
    settings={
        "max_iterations": 5,
        "max_execution_time": 300,
        "tools": []
    }
)

print(f"Agent created: {agent.key}")
```

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

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

async function createAgent() {
  const agent = await client.agents.create({
    key: "support-agent",
    role: "Customer Support Assistant",
    description: "Handles customer inquiries and provides support",
    instructions: "You are a helpful customer support assistant. Answer customer questions clearly and concisely. If you cannot help, escalate to a human agent.",
    path: "Default/agents",
    model: "openai/gpt-4o",
    settings: {
      maxIterations: 5,
      maxExecutionTime: 300,
      tools: []
    }
  });

  console.log(`Agent created: ${agent.key}`);
}

createAgent();
```

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

### Track Contact Metrics via API and SDKs

Source: https://docs.orq.ai/docs/analytics/contact

This snippet demonstrates tracking contact metrics using ORQ AI. It includes a cURL example for direct API usage with contact ID in headers and TypeScript/Python examples for SDK implementation, where contact ID can be initialized during client setup.

```bash
curl 'https://api.orq.ai/v2/deployments/invoke' \
  -H 'Authorization: Bearer {apiKey}' \
  -H 'X-ORQ-CONTACT-ID: <external_id>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
     "key": "<deployment_key>",
     "context": {
        "environments": []
     }
  }' \
  --compressed
```

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

const client = new Orq({
  apiKey: 'orq-api-key',
  environment: 'production',
  // Optionally initiate the contactId for the session
  contactId: '<contactId>'
});
```

```python
import os
from orq_ai_sdk import Orq

client = Orq(
    api_key=os.environ.get("ORQ_API_KEY", "__API_KEY__"),
    environment="production",
    contact_id="<contact_id>"
)
```

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

### Install orq-ai-sdk using pip

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

Installs the orq-ai-sdk package, which is necessary for interacting with Orq's services. This command is typically run in a Python environment or notebook.

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

```

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

### Create AI Agent using cURL, Python, and TypeScript

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

This snippet demonstrates how to create an AI agent using the Orq.ai API. It defines the agent's configuration, including its key, role, instructions, model, and settings. The examples cover cURL for direct API calls, Python using the orq_ai_sdk, and TypeScript using the @orq-ai/node SDK.

```cURL
curl -X POST https://api.orq.ai/v2/agents \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "key": "simple-agent-1",
    "role": "Assistant",
    "description": "A helpful assistant for general tasks",
    "instructions": "Be helpful and concise",
    "path": "Default/agents",
    "model": {
      "id": "openai/gpt-4o"
    },
    "settings": {
      "max_iterations": 3,
      "max_execution_time": 300,
      "tools": []
    }
  }'
```

```Python
from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    agent = orq.agents.create(
        key="simple-agent-1",
        role="Assistant",
        description="A helpful assistant for general tasks",
        instructions="Be helpful and concise",
        path="Default/agents",
        model={"id": "openai/gpt-4o"},
        settings={
            "max_iterations": 3,
            "max_execution_time": 300,
            "tools": []
        }
    )

    print(f"Agent created: {agent.key}")
```

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

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

async function createAgent() {
    const agent = await orq.agents.create({
      key: 'simple-agent-1',
      role: 'Assistant',
      description: 'A helpful assistant for general tasks',
      instructions: 'Be helpful and concise',
      path: 'Default/agents',
      model: {
        id: 'openai/gpt-4o'
      },
      settings: {
        maxIterations: 3,
        maxExecutionTime: 300,
        tools: []
      }
    });

    console.log(`Agent created: ${agent.key}`);
  }

createAgent();
```

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

### Install orq.ai Node.js SDK via npm

Source: https://docs.orq.ai/docs/quick-start

Installs the latest version of the orq.ai Node.js SDK using npm. This command should be executed in a terminal within your project directory.

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

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

### Example Output for IT Assistant

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

Example of the output generated by the Advanced RAG IT Assistant when asked about a laptop connectivity issue.

```python
❯ python3 it_assistant.py
Answer: Issue Classification: Network connection and application access failure after macOS update
Confidence Level: High

Primary Solution:

1. Verify your laptop's wireless adapter is enabled and functioning properly:
   - Go to System Preferences > Network and check that the wireless adapter is listed and "Connected" to the network.
   - If the adapter is disabled, click the "Turn Wi-Fi On" button.

2. Check your corporate WiFi network settings:
   - Ensure you are attempting to connect to the correct SSID (network name) for your office.
   - Confirm the network security settings (e.g. WPA2, 802.1X) match what your IT team has provided.
   - If you have previously connected successfully, the network details should be pre-configured.

3. Reset your network settings:
   - Go to System Preferences > Network
   - Click the "Advanced" button, then the "Renew DHCP Lease" option.
   - If that doesn't work, try deleting the existing WiFi network and re-adding it.

```

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

### API Call Examples for Creating an Evaluator

Source: https://docs.orq.ai/docs/evaluators/api-usage

Demonstrates how to call the orq.ai API to create a Python evaluator. Includes examples using cURL, Python SDK, and TypeScript SDK. The request payload includes guardrail configuration and the Python evaluator code.

```bash
curl --request POST \
     --url https://api.orq.ai/v2/evaluators \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ORQ_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "guardrail_config": {
    "enabled": true,
    "type": "number",
    "value": 5,
    "operator": "lte"
  },
  "type": "python_eval",
  "path": "Default/Evaluators",
  "key": "MyEvaluator",
  "code": "def evaluate(log):\n  output_size = len(log[\"output\"])\n  reference_size = len(log[\"reference\"])\n  return abs(output_size - reference_size)\n"
}'
```

```python
from orq_ai_sdk import Orq
import os

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

    res = orq.evals.create(request={
      "guardrail_config": {
        "enabled": True,
        "type": "number",
        "value": 5,
        "operator": "lte"
      },
      "type": "python_eval",
      "path": "Default/Evaluators",
      "key": "MyEvaluator",
      "code": "def evaluate(log):\n  output_size = len(log[\"output\"])\n  reference_size = len(log[\"reference\"])\n  return abs(output_size - reference_size)\n"
      })

      assert res is not None

      # Handle response
      print(res)
```

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

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

async function run() {
    const result = await orq.evals.create({
      guardrailConfig: {
        enabled: true,
        type: "number",
        value: 5,
        operator: "lte"
      },
      type: "python_eval",
      path: "Default/Evaluators",
      key: "MyEvaluator",
      code: "def evaluate(log):\n  output_size = len(log[\"output\"])\n  reference_size = len(log[\"reference\"])\n  return abs(output_size - reference_size)\n"
    });

    console.log(result);
}

```

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

### RAG System Execution Example (Python)

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

This example shows the output of a RAG system when executed with a Python script. It displays a sample answer to a question about company policy and lists the sources from which the information was retrieved, including the source file name and a snippet of the content.

```python
❯ python3 rag_system.py
Answer: Based on our company documentation, our return policy allows customers to return items within 30 days of purchase with a valid receipt. Items must be in original condition and packaging. Refunds are processed within 5-7 business days after we receive the returned item.

Sources:
- company_policies.pdf: Return Policy: All items can be returned within 30 days of purchase provided...
- customer_service_guide.pdf: For returns, customers must provide proof of purchase and items must be...
```

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

### Install OpenAI SDK for Node.js

Source: https://docs.orq.ai/docs/tutorials/buildingcustomersupportchatwithaigateway

Installs the official OpenAI SDK for Node.js. This allows your application to interact with OpenAI's language models and other services.

```bash
npm install openai
```

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

### JSON System Prompt with Dynamic Placeholders

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

An example of a system prompt that utilizes dynamic inputs for personalization. Placeholders like {{company_name}} and {{customer_tier}} are replaced with values from the `orq.inputs` object.

```json
{
  "role": "system",
  "content": "You are a helpful customer support agent for {{company_name}}. Use available knowledge to assist {{customer_tier}} customers."
}
```

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

### Install AutoGen and OpenTelemetry Packages

Source: https://docs.orq.ai/docs/observability/frameworks/autogen

Installs the core AutoGen library, the OpenTelemetry SDK, and the OTLP HTTP exporter necessary for sending trace data. It also installs the OpenAI package for LLM integration.

```bash
# Core AutoGen and OpenTelemetry packages
pip install pyautogen opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

# LLM providers
pip install openai
```

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

### Install orq.ai Python SDK via pip

Source: https://docs.orq.ai/docs/quick-start

Installs the orq.ai Python SDK using pip. This command is used to add the SDK to your Python environment, enabling you to interact with orq.ai services.

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

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

### Quick Start: TypeScript Example

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

Demonstrates how to use the OpenAI API with Zod schemas to get type-safe JSON responses in TypeScript.

```APIDOC
## POST /v1/chat/completions (with response_format)

### Description
This endpoint allows for generating chat completions with a specified response format, including JSON schema validation using libraries like Zod. It ensures that the LLM output conforms to a predefined schema, providing type-safe access to the parsed data.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The model to use for generating completions.
- **messages** (array of objects) - Required - The messages to send to the model.
  - **role** (string) - Required - The role of the message (e.g., 'user', 'system', 'assistant').
  - **content** (string) - Required - The content of the message.
- **response_format** (object) - Optional - Specifies the response format. For JSON schema validation, use `zodResponseFormat`.
  - **type** (string) - Required - Should be set to 'json_object' or 'json_schema'.
  - **json_schema** (object) - Required if type is 'json_schema'.
    - **name** (string) - Required - The name or identifier for the schema.
    - **schema** (object) - Required - The JSON schema definition.

### Request Example
```typescript
import { z } from "zod";
import { zodResponseFormat } from "openai/helpers/zod";

// Define your schema
const UserSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string(),
  skills: z.array(z.string()),
});

const response = await openai.beta.chat.completions.parse({
  model: "openai/gpt-4o",
  messages: [
    {
      role: "user",
      content:
        "Extract info: John Doe, 30, [email\u00a0protected], knows Python and React",
    },
  ],
  response_format: zodResponseFormat(UserSchema, "user"),
});

// Type-safe access
const user = response.choices[0].message.parsed;
console.log(user.name); // Guaranteed string
console.log(user.skills); // Guaranteed string array
```

### Response
#### Success Response (200)
- **choices** (array of objects) - The list of completion choices.
  - **message** (object)
    - **role** (string) - The role of the message.
    - **content** (string) - The content of the message.
    - **parsed** (object) - The parsed and validated JSON object according to the schema.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"name\": \"John Doe\", \"age\": 30, \"email\": \"[email\u00a0protected]\", \"skills\": [\"Python\", \"React\"]}",
        "parsed": {
          "name": "John Doe",
          "age": 30,
          "email": "[email\u00a0protected]",
          "skills": ["Python", "React"]
        }
      }
    }
  ]
}
```
```

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

### Create Memory Store with cURL, Python, and TypeScript

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

This snippet demonstrates how to create a new memory store. It requires a unique key, an optional description, a project path, and embedding model configuration. The examples show usage with cURL, Python, and TypeScript, utilizing the ORQ_API_KEY for authentication.

```bash
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data \
'{
    "key": "customer_information",
    "description": "Store for customer interaction history and preferences",
    "path": "Default/agents",
    "embedding_config": {
      "model": "openai/text-embedding-3-small"
    }
  }'
```

```python
from orq_ai_sdk import Orq
import os

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

store = client.memory_stores.create(
    request={
        "key": "customer_information",  # Unique, immutable identifier
        "description": "Store for customer interaction history and preferences",
        "path": "Default/agents",  # Project path (required)
        "embedding_config": {
            "model": "openai/text-embedding-3-small"  # Embedding model for semantic search
        }
    }
)
```

```typescript
await client.memoryStores.create({
  key: 'customer_information', // Unique, immutable identifier
  description: 'Store for customer interaction history and preferences',
  path: 'Default/agents', // Project path (required)
  embedding_config: {
    model: 'openai/text-embedding-3-small', // Embedding model for semantic search
  },
});
```

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

### Invoke Journey Plan Agent

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

This section details how to invoke the 'journey-plan-agent' to get responses. It provides examples in cURL, Python, and TypeScript.

```APIDOC
## POST /v2/agents/journey-plan-agent/responses

### Description
Invokes the 'journey-plan-agent' to generate a response based on a user's message. This is a synchronous call that returns the agent's final output.

### Method
POST

### Endpoint
https://api.orq.ai/v2/agents/journey-plan-agent/responses

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be application/json.

#### Request Body
- **message** (object) - Required - The user's message to the agent.
  - **role** (string) - Required - The role of the message sender (e.g., 'user').
  - **parts** (array) - Required - An array of message parts.
    - **kind** (string) - Required - The type of part (e.g., 'text').
    - **text** (string) - Required - The actual text content of the message part.

### Request Example (cURL)
```bash
curl -X POST https://api.orq.ai/v2/agents/journey-plan-agent/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ 
    "message": { 
      "role": "user", 
      "parts": [ 
        { 
          "kind": "text", 
          "text": "What is happening in Budapest on the 26th and 27th of August this year?"
        } 
      ] 
    } 
  }'
```

### Response
#### Success Response (200)
- **output** (array) - The agent's response.
  - **parts** (array)
    - **text** (string) - The text content of the response part.
- **usage** (object) - Information about token usage.

#### Response Example
```json
{
  "output": [
    {
      "role": "assistant",
      "parts": [
        {
          "kind": "text",
          "text": "Here are some events happening in Budapest on August 26th and 27th..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 50,
    "output_tokens": 100,
    "total_tokens": 150
  }
}
```
```

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

### Install LiteLLM and OpenTelemetry Packages (Bash)

Source: https://docs.orq.ai/docs/observability/frameworks/litellm

Installs the core LiteLLM package, OpenTelemetry SDK, OTLP exporter, and the LiteLLM proxy. This is the foundational step for enabling tracing.

```bash
# Core LiteLLM and OpenTelemetry packages
pip install litellm opentelemetry-sdk opentelemetry-exporter-otlp
pip install 'litellm[proxy]'
```

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

### Install LangChain and LangGraph Dependencies

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

Installs the necessary Python libraries for LangChain, LangChain-OpenAI, and LangGraph. This is the first step to integrating Orq.ai with these frameworks.

```bash
pip install langchain langchain-openai langgraph
```

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

### Install Dependencies for Orq.ai and Pinecone Integration

Source: https://docs.orq.ai/docs/tutorials/using-thirdparty-vectordbs-with-orq

Installs the necessary Python packages for integrating Orq.ai with Pinecone and other supporting tools. This includes the Pinecone client, Orq SDK, and request libraries, essential for setting up custom RAG workflows.

```bash
!pip install -qU \
    pinecone==6.0.2 \
    pinecone-notebooks \
    orq-ai-sdk \
    requests
```

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

### Install Vercel AI SDK and OpenTelemetry Dependencies

Source: https://docs.orq.ai/docs/observability/frameworks/vercel

Installs the core Vercel AI SDK, necessary OpenTelemetry packages for tracing, and optional provider SDKs. Ensure Node.js 18+ is used.

```bash
npm install ai@latest
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
npm install @opentelemetry/instrumentation @opentelemetry/resources
npm install @opentelemetry/semantic-conventions

# Provider SDKs (choose what you need)
npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

# Optional: For React applications
npm install @ai-sdk/react
```