> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Quick Start | Observe > Connect an existing LangGraph, Vercel AI, Pydantic AI, OpenAI Agents SDK, or Agno application to orq.ai and start evaluating outputs in minutes. Already have an agent? Add a few lines of OpenTelemetry setup to start seeing full trace visibility and cost tracking in **orq.ai**. ### Create your orq.ai account [Sign up](https://my.orq.ai/auth/signup) for a free **orq.ai** account and set up your workspace. ### Get your API key Open **Organization > [API Keys](/docs/administer/api-keys)** in the [AI Studio](https://my.orq.ai). Click Create API Key, give it a name, and copy it. Then open a terminal and run the command below, replacing `your-api-key-here` with the copied key. The code samples in the next steps read it from this environment variable. ```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}} export ORQ_API_KEY="your-api-key-here" ``` ```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}} $env:ORQ_API_KEY = "your-api-key-here" ``` ### Connect your framework Install the dependencies: ```bash Python theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install orq-ai-sdk langchain langchain-openai langgraph ``` ```bash Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @orq-ai/node @langchain/core @langchain/langgraph @langchain/openai zod ``` Call `setup()` once before defining the graph. Every node, tool call, and LLM step is then captured and shipped to **orq.ai**. ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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) ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 = { 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); ``` See the [LangGraph Observability guide](/docs/proxy/frameworks/langgraph#observability) for streaming, tool tracing, and **Control Tower** asset capture. Install the dependencies: ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} pnpm add ai@latest @vercel/otel @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/semantic-conventions @ai-sdk/openai ``` Set the environment variables: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}" export OTEL_RESOURCE_ATTRIBUTES="service.name=vercel-ai-app,service.version=1.0.0" export OPENAI_API_KEY="" ``` Create an `instrumentation.js` file at the root of your project: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} // instrumentation.js import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel'; export function register() { registerOTel({ serviceName: 'your-project-name', traceExporter: new OTLPHttpJsonTraceExporter({ url: 'https://my.orq.ai/v2/otel/v1/traces', headers: { 'Authorization': `Bearer ${process.env.ORQ_API_KEY}`, }, }), }); } ``` Then enable telemetry on each generation call: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} // index.js import { register } from './instrumentation.js'; import { generateText } from "ai"; import { openai } from "@ai-sdk/openai"; register(); const result = await generateText({ model: openai("gpt-4.1"), prompt: "Write a short story about a robot", experimental_telemetry: { isEnabled: true, }, }); ``` See the [Vercel AI Observability guide](/docs/proxy/frameworks/vercel-ai#observability) for streaming, structured output, and agent detection examples. Install the dependencies: ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install pydantic-ai openai opentelemetry-sdk opentelemetry-exporter-otlp 'logfire>=4' ``` Set the environment variables: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}" export OTEL_RESOURCE_ATTRIBUTES="service.name=pydantic-ai-app,service.version=1.0.0" export OPENAI_API_KEY="" ``` Configure logfire and instrument **Pydantic AI** before running the agent: ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import logfire from pydantic_ai import Agent logfire.configure( service_name='orq-traces', send_to_logfire=False, metrics=False, ) logfire.instrument_pydantic_ai() agent = Agent('openai:gpt-4o-mini') result = agent.run_sync('What is the capital of France?') print(result.output) ``` See the [Pydantic AI Observability guide](/docs/proxy/frameworks/pydantic-ai#observability) for streaming, structured output, and tool tracing. Install the dependencies: ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install opentelemetry-sdk opentelemetry-instrumentation opentelemetry-exporter-otlp openai-agents orq-ai-sdk ``` Set the environment variables: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}" export OTEL_RESOURCE_ATTRIBUTES="service.name=openai-agents-app,service.version=1.0.0" export OPENAI_API_KEY="" ``` Instrument before running any agents: ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 # Set up OpenTelemetry tracer_provider = TracerProvider() tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) # Instrument OpenAI agents with Orq.ai OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer_provider) agent = Agent(name="Assistant", instructions="You are a helpful assistant") result = Runner.run_sync(agent, "Write a haiku about recursion in programming.") print(result.final_output) ``` All subsequent `Runner.run_sync()` / `Runner.run()` calls are automatically traced. See the [OpenAI Agents Observability guide](/docs/proxy/frameworks/openai-agents#observability) for multi-agent handoff tracing and **Control Tower** asset capture. Install the dependencies: ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install agno openai opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http openinference-instrumentation-agno ``` Set the environment variables: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}" export OTEL_RESOURCE_ATTRIBUTES="service.name=agno-app,service.version=1.0.0" export OPENAI_API_KEY="" ``` Instrument before creating your agent: ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 from openinference.instrumentation.agno import AgnoInstrumentor from agno.agent import Agent from agno.models.openai import OpenAIChat tracer_provider = TracerProvider() tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) trace_api.set_tracer_provider(tracer_provider) AgnoInstrumentor().instrument(tracer_provider=tracer_provider) agent = Agent(model=OpenAIChat(id="gpt-4o-mini")) print(agent.run("What is the capital of France?").content) ``` See the [Agno Observability guide](/docs/proxy/frameworks/agno#observability) for tool tracing and multi-agent examples. Using a different framework? **orq.ai** supports observability for **LangChain**, **LiteLLM**, **CrewAI**, **AWS Strands**, **Mastra**, and more. See the [Frameworks overview](/docs/proxy/frameworks/overview) for the full list and setup guides. ### View your traces Run the agent and open [**Traces**](https://my.orq.ai) in the **AI Studio**. Every request will appear with model, latency, token counts, and cost. For agentic frameworks, individual tool calls and steps appear as child spans. ### Analyze traces with MCP Install the [**Orq MCP** server](/docs/workspace-mcp) in the editor or AI assistant, then ask the coding assistant: ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Show me the 10 slowest traces from the last 24 hours and explain what might be causing the latency ``` The assistant queries the **Orq MCP** and returns an analysis like this: ## Troubleshooting 1. Confirm the variable is set: `echo $ORQ_API_KEY` 2. Verify the key is active under **Organization > API Keys** 3. Confirm the key is passed in the `Authorization: Bearer` header on your OTLP exporter, not as a query parameter 1. Confirm your OTLP endpoint is set to `https://my.orq.ai/v2/otel` (or `/v2/otel/v1/traces` for exporters that require the full path) 2. Check that the workspace in your API key matches the **AI Studio** workspace you are viewing 3. Traces can take a few seconds to appear, wait 10 seconds and refresh *** Label and review spans to build high-quality evaluation datasets from real production traffic. Track cost, latency, error rates, and token usage across models and deployments over time. Use your traced data as a baseline to compare prompts, models, and configurations side by side. Build and deploy a native **orq.ai** agent with tools, memory, and full **AI Studio** management.