The Agents Beta API provides powerful endpoints for creating, executing, and managing AI agents with support for tools, memory, knowledge bases, and real-time streaming.
curl -X POST https://api.orq.ai/v2/agents/simple-agent-1/responses \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_key": "simple-agent-1", "background": false, "message": { "role": "user", "parts": [ { "kind": "text", "text": "I'\''m preparing a technical presentation on microservices architecture. Can you help me create an outline covering the key benefits, challenges, and best practices?" } ] }}'
The response will be sent back with a task detail containing the status and metadata, including a unique id.
Set background: false (default) to wait for the agent execution to complete. Set background: true to return immediately without waiting for completion.Use the task id in subsequent calls to continue the conversation with the agent.
By default, invoking an agent always routes to the version tagged as latest. To target a specific published version, append @version-number to the agent key.
After receiving a task response, you can continue the conversation by sending additional messages to the same agent. This allows for multi-turn interactions where the agent maintains context from previous exchanges.To continue a task, use the /v2/agents/{key}/responses endpoint and provide the task_id from the previous response. The task must be in an inactive state to continue.
task_id: Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state.
Copy
curl -X POST https://api.orq.ai/v2/agents/simple-agent-1/responses \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_key": "simple-agent-1", "task_id": "01K6D8QESESZ6SAXQPJPFQXPFT", "background": false, "message": { "role": "user", "parts": [ { "kind": "text", "text": "Great outline! Can you expand on the challenges section? I want to dive deeper into data consistency approaches and monitoring best practices." } ] }}'
The continuation will return a new task ID representing the extended conversation:
Always verify that your chosen model supports the file types you’re using. Vision models are typically required for image processing and PDF processing
Knowledge Base integration with Agents enables AI systems to access and query your custom data sources during agent execution. This powerful combination allows agents to ground their responses in your specific domain knowledge, documents, and datasets.
curl -X POST https://api.orq.ai/v2/agents/book-assistant/responses \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_key": "book-assistant", "background": false, "message": { "role": "user", "parts": [ { "kind": "text", "text": "What is the coat of arms of the Apafi family?" } ] }}'
Agents should use retrieve_knowledge_bases to discover available knowledge bases before querying them. Guide your agent with instructions like: First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.
Memory Management enables agents to maintain persistent context and learn from previous interactions across conversations. By integrating with Memory Stores, agents can store, retrieve, and manage information that persists beyond individual sessions.
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "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" ]}'
Agents must use the retrieve_memory_stores tool first to discover available memory stores before they can query or write to them. Include instructions in your system prompt like: Use retrieve_memory_stores to see what memory stores are available, then use query_memory_store to search for relevant information before responding.
To call the Agent, we’ll use the Responses API with an Embedded message and Linked memory.
Copy
curl -X POST https://api.orq.ai/v2/agents/agent-memories/responses \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "agent-memories", "memory": { "entity_id": "customer_456" }, "message": { "role": "user", "parts": [ { "kind": "text", "text": "Do you remember what is my name?" } ] }}'
You can use multiple memory stores per call, ensure that the entity_id sent during the calls maps the same way to all previously declared memory stores during agent creation.
Tools extend agent capabilities by providing access to external systems, APIs, and custom functionality. Agents can leverage multiple tool types to handle complex tasks requiring data processing, web interactions, or custom business logic.To declare a tool during an agent run, use the settings.tools array to import a Tool.
Important: Your agent’s instructions must explicitly mention the available tools and when to use them. The model won’t invoke tools unless your instructions clearly describe what each tool does, when it should be called, and how to use it. See the examples below for best practices on writing tool-aware instructions.
Custom business logic with OpenAPI-style schemasFunction tools allow you to define custom functions that agents can call. First, create an agent with function tools configured, then invoke it using the responses endpoint.
1
Create Agent with Function Tools
Copy
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "journey-plan-agent", "role": "Itinerary Assistant", "description": "An agent that helps plan trips and find local events", "instructions": "Help users plan their journey. Call the current_date tool first to know the current date, then use get_local_events to find events.", "settings": { "max_iterations": 5, "max_execution_time": 300, "tools": [ { "type": "current_date" }, { "type": "function", "key": "get_local_events", "display_name": "Get Local Events", "description": "Retrieves local events for a given city and date", "function": { "name": "get_local_events", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "The name of the city" }, "date": { "type": "string", "description": "The date (YYYY-MM-DD)" } }, "required": ["city", "date"] } } } ] }, "model": "openai/gpt-4o", "path": "Default/agents"}'
2
Invoke the Agent
Copy
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?" } ] }}'
3
View Streaming Response
For the above method, using the Stream Run execution, we’re getting the following payloads showing the agent’s reasoning process:
Agent Calls Current Date Tool
What’s happening: The agent analyzes the user’s question and decides it needs to know the current date first (following system instructions). It calls the orq_current_date tool.
Tool Result: Date Retrieved — The orq_current_date tool returns 2025-10-03, so the agent now knows the user is asking about past events (August 26-27, 2025 has already occurred).
What’s happening: With date context established, the agent decides to make TWO parallel calls to the get_local_events function tool (one for each date requested).
What’s happening: Since get_local_events is a function tool (not a built-in tool), the agent pauses and waits for you to implement the function and provide results via the continuation API.
Embed code tools with executable python code, for this example we’ll be embedding a password generator.
Copy
import random import string def generate_password(length, include_numbers, include_symbols): """Generate a secure random password.""" # Start with letters chars = string.ascii_letters # Add numbers if requested if include_numbers: chars += string.digits # Add symbols if requested if include_symbols: chars += '!@#$%^&*()_+-=[]{}|;:,.<>?' # Generate password password = ''.join(random.choice(chars) for _ in range(length)) return { "password": password, "length": len(password), "includes_numbers": include_numbers, "includes_symbols": include_symbols, "character_types": len(chars) } # Execute with params result = generate_password( params.get('length', 12), params.get('include_numbers', True), params.get('include_symbols', True) )
Tip: Converting Python Code to Payload StringTo convert your Python code into a JSON-safe string for the payload, use this shell command:Bash
Copy
cat your_script.py | jq -Rs .
Once the payload string is generated, it can be embedded within the code_tool section as follows:
1
Create Agent with Code Tool
Copy
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "password-helper-agent", "role": "Password Generator Assistant", "description": "Generate secure passwords with customizable options", "instructions": "You are a helpful password generation assistant. Use the password_generator tool to create secure passwords based on user requirements. Always explain the password characteristics (length, included character types).", "settings": { "max_iterations": 3, "max_execution_time": 300, "tools": [ { "type": "code", "key": "password_generator", "display_name": "Password Generator", "description": "Generate secure passwords with numbers and symbols", "language": "python", "code": "import random\nimport string\n\ndef generate_password(length, include_numbers, include_symbols):\n \"\"\"Generate a secure random password.\"\"\"\n chars = string.ascii_letters\n \n if include_numbers:\n chars += string.digits\n \n if include_symbols:\n chars += \"!@#$%^&*()_+-=[]{}|;:,.<>?\"\n \n password = \"\".join(random.choice(chars) for _ in range(length))\n \n return {\n \"password\": password,\n \"length\": len(password),\n \"includes_numbers\": include_numbers,\n \"includes_symbols\": include_symbols,\n \"character_types\": len(chars)\n }\n\nresult = generate_password(\n params.get(\"length\", 12),\n params.get(\"include_numbers\", True),\n params.get(\"include_symbols\", True)\n)", "parameters": { "type": "object", "properties": { "length": { "type": "integer", "description": "Password length", "default": 12 }, "include_numbers": { "type": "boolean", "description": "Include numbers in password", "default": true }, "include_symbols": { "type": "boolean", "description": "Include symbols in password", "default": true } } } } ] }, "model": "openai/gpt-4o", "path": "Default/agents"}'
2
Invoke the Agent
The tool is then usable as any other tool. Callable by its key (here password_generator). The tool has access to the declared parameters as input for execution.
Copy
curl -X POST https://api.orq.ai/v2/agents/password-helper-agent/responses \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": { "role": "user", "parts": [ { "kind": "text", "text": "Generate a 16-character password with numbers and symbols for my new database account" } ] }}'
External API integrations allowing agents to call HTTP endpoints. HTTP tools consist of a blueprint (the API request template) and arguments (dynamic parameters).
Blueprint Configuration: The blueprint defines the HTTP request structure using {{parameter}} syntax for placeholders that will be replaced with argument values.
Key Components:
Blueprint URL: Target endpoint with parameter placeholders
Method: HTTP verb (GET, POST, PUT, DELETE)
Headers: Optional custom headers with encryption support
Body: Optional request payload
Arguments: Dynamic parameters passed from the model with types and descriptions
send_to_model: Whether the model can see this parameter (default: true)
default_value: Fallback value if not provided by the model
1
Create HTTP Tool and Agent
First, create an HTTP tool via the API, then create an agent that references it by its key.Step 1: Create the HTTP Tool
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "weather-analyst-1", "role": "Weather Analysis Assistant", "description": "An agent that fetches and analyzes weather data for locations", "instructions": "You are a weather analysis expert. Use the weather_api tool to get current weather information for any location the user asks about. Provide detailed weather analysis including temperature, conditions, and recommendations.", "settings": { "max_iterations": 3, "max_execution_time": 300, "tools": [ { "type": "http", "key": "weather_api" } ] }, "model": "openai/gpt-4o", "path": "Default/agents"}'
2
Invoke the Agent
Copy
curl -X POST https://api.orq.ai/v2/agents/weather-analyst-1/responses \-H "Authorization: Bearer $ORQ_API_KEY" \-H "Content-Type: application/json" \-d '{"message": {"role": "user","parts": [ { "kind": "text", "text": "What is the current weather in Paris, France?" }]}}'
HTTP Tool Payload Structure
When creating an HTTP tool via the API, use this structure:
Always set "encrypted": true for sensitive headers like API keys or authentication tokens. This ensures credentials are securely stored in the platform.
Model Context Protocol (MCP) tools enable agents to interact with MCP servers for access to specialized services and external systems with standardized protocols. The Orq.ai documentation MCP server provides documentation search and code generation assistance.
1
Create MCP Tool
First, create an MCP tool that connects to an MCP server, then create an agent that references it by its tool ID.
The tool creation will return a tool_id that you’ll use to reference this MCP tool in agents.
2
Create Agent with MCP Tool
Create an agent that references the MCP tool by its tool_id.
Copy
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "orq-docs-assistant-agent", "role": "Orq.ai Documentation Assistant", "description": "An agent that searches Orq.ai documentation and provides integration guidance", "instructions": "You are an Orq.ai documentation assistant. Use the orq_docs_mcp tool to search the Orq.ai documentation, find relevant guides, and help users understand how to use Orq.ai features. Provide accurate, helpful information based on the documentation.", "settings": { "max_iterations": 5, "max_execution_time": 300, "tools": [ { "type": "mcp", "tool_id": "TOOL_ID_FROM_PREVIOUS_STEP" } ] }, "model": "openai/gpt-4o", "path": "Default/agents"}'
3
Invoke the Agent
Copy
curl -X POST https://api.orq.ai/v2/agents/orq-docs-assistant-agent/responses \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": { "role": "user", "parts": [ { "kind": "text", "text": "How do I integrate Vercel AI SDK with Orq.ai? Can you provide the setup steps?" } ] }}'
Multi-agent workflows enable complex task orchestration by creating teams of specialized agents that work together hierarchically. This system allows you to build sophisticated AI applications where different agents handle specific domains or functions, coordinated by an orchestrator agent.Agents can invoke sub-agents using a hierarchical agent system:
Orchestrator: Main agent that delegates tasks.
Sub-agents: Specialized agents for specific functions.
Delegation: Automatic task routing based on agent capabilities.
Context Sharing: Shared memory and knowledge between agents.
We are creating two sub-agents that we will be later orchestrating through an agent run.
Calling the Create Agent endpoint to create a Youth Agent
Copy
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "youth-agent", "role": "Agent specialized in talking to the younger generation until 25 years old", "description": "An agent which is tailored to a youthful tone", "instructions": "You are an agent who is tasked with talking to people under 25 years old and tries to match the tone that the younger generation uses in an informal, but respectful way. You use hip lingo actually and a bunch of emojis that helps they relate to you.", "settings": { "max_iterations": 15, "max_execution_time": 300, "tools": [ { "type": "current_date" } ] }, "model": "openai/gpt-4o", "path": "Default/agents"}'
Calling the Create Agent endpoint to create a Formal Agent
Copy
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "formal-agent", "role": "Agent specialized in talking to a more mature audience", "description": "An agent which is tailored to formal communication", "instructions": "You are a professional agent responsible for engaging with individuals under 25 years of age. Your communication should maintain a formal and respectful tone while remaining accessible to younger audiences.", "settings": { "max_iterations": 15, "max_execution_time": 300, "tools": [ { "type": "current_date" } ] }, "model": "openai/gpt-4o", "path": "Default/agents"}'
To update an existing agent, issue a similar call using the PATCH method to an existing agent_key. e.g. PATCH /v2/agents/youth-agent . To learn more, see Updating an Agent.
Orchestrator agents must use the retrieve_agents tool to discover available sub-agents before delegating tasks.
Include instructions like: “Use retrieve_agents to see what specialized agents are available, then use call_sub_agent to delegate appropriate tasks based on their capabilities.”
Both tools must be included in the orchestrator’s configuration.
Now that you have created the sub-agents, create the orchestrator agent using the CRUD endpoint. Reference the sub-agents through the team_of_agents field by their keys and roles. You can later update this orchestrator (and its sub-agents) using the PATCH endpoint.
Calling the Create Agent endpoint to create an Orchestrator Agent
Copy
curl -X POST https://api.orq.ai/v2/agents \ -H "Authorization: Bearer $ORQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "tone-orchestrator", "role": "Book Assistant", "description": "A friendly orchestrator agent who strives to help people by coordinating specialized sub-agents", "instructions": "Answer the question of the user using your sub agents. Delegate tasks to your sub agents who will write the message and you will provide it in the final response with NO CHANGES. You create the answer and then you need to call the sub-agents after retrieving them and they will need to rephrase it according to their instructions. Instruct the sub-agents what they need to do, make their task clear as the orchestrator. Provide clear instructions to the sub agents what they need to do.", "settings": { "max_iterations": 15, "max_execution_time": 600, "tool_approval_required": "none", "tools": [ { "type": "current_date" }, { "type": "retrieve_agents" }, { "type": "call_sub_agent" } ] }, "model": "openai/gpt-4o", "path": "Default/agents", "team_of_agents": [ { "key": "youth-agent", "role": "The youth agent for ages under 25" }, { "key": "formal-agent", "role": "The formal agent for ages above 25" } ]}'
You can update the orchestrator agent and its sub-agents at any time using the PATCH endpoint (e.g., PATCH /v2/agents/tone-orchestrator). This allows you to refine instructions, add or remove sub-agents from the team_of_agents array, or modify settings while keeping the same agent key.
Once the orchestrator agent is created, invoke it by referencing its key. The orchestrator will use the sub-agents defined in the team_of_agents array during the creation step.
Calling the Create Response endpoint with the Orchestrator Agent key
Copy
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}'
The request body includes these key fields:
message (required): The user message in A2A format with role and parts array
variables (optional): Template variables for dynamic content substitution
metadata (optional): Custom metadata to track the request
background (optional): Set to true for asynchronous execution, false for synchronous (waits for completion)
identity (optional): Include user information for context
thread (optional): Reference previous conversation threads for continuity
memory (optional): Entity-based memory for personalized context
For the basic orchestrator invocation, only the message field is required.
