Skip to main content
POST
/
run
curl --request POST \
  --url https://api.starlight-search.com/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "task": "What is the weather in Berlin?",
  "model": "gpt-4.1-nano",
  "base_url": "https://api.openai.com/v1/chat/completions",
  "tools": [
    "ExaSearchTool",
    "VisitWebsite"
  ]
}
'
{
  "result": "<string>",
  "steps": [
    {
      "step_number": 123,
      "action": "<string>",
      "tool_used": "<string>",
      "result": "<string>"
    }
  ],
  "tool_calls": [
    {
      "tool_name": "<string>",
      "arguments": {},
      "result": "<string>",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ],
  "metadata": {
    "total_steps": 123,
    "execution_time": 123
  }
}

​
Overview

The /run endpoint is the primary way to interact with Lumo agents. It accepts a task description and executes it using the specified agent type, automatically managing tool selection, context, and execution flow.

​
Request Parameters

​
Required Parameters

  • task (string): The task description that the agent should complete
  • model (string): The AI model identifier (e.g., “gpt-4.1-nano”)
  • base_url (string): The base URL for your chat completions API endpoint

​
Optional Parameters

  • tools (array): List of available tool identifiers (e.g., [“ExaSearchTool”, “VisitWebsite”])
  • max_steps (integer): Maximum number of steps the agent can take
  • agent_type (string): Agent type - “function-calling” (default) or “code-agent”
  • messages (array): Optional conversation history or system messages

​
Examples

​
Basic Function Calling Agent

curl --location 'https://api.starlight-search.com/run' \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "task": "What is the weather in Berlin?",
    "model": "gpt-4.1-nano",
    "base_url": "https://api.openai.com/v1/chat/completions",
    "tools": ["ExaSearchTool", "VisitWebsite"]
}'

​
Code Agent with Maximum Steps

curl --location 'https://api.starlight-search.com/run' \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "task": "Search for the top 5 AI companies and get their current stock prices",
    "model": "gpt-4.1-mini",
    "base_url": "https://api.openai.com/v1/chat/completions",
    "tools": ["ExaSearchTool", "VisitWebsite"],
    "agent_type": "code-agent",
    "max_steps": 5
}'

​
Response Format

On success, the API returns a JSON object containing:
  • result: The final result or answer from the agent
  • steps: Array of steps taken by the agent
  • tool_calls: Details of tool calls made during execution
  • metadata: Additional metadata (execution time, total steps, etc.)

​
Agent Types

​
Function Calling Agent (Default)

The function calling agent uses automatic function selection and execution. It’s ideal for:
  • Multi-step tasks requiring sequential actions
  • External data retrieval
  • Tool interactions

​
Code Agent

The code agent uses executable Python code as actions. It’s ideal for:
  • Complex multi-step workflows
  • Data processing with loops and conditionals
  • Tasks requiring self-correction and debugging
  • Up to 30% fewer actions than function calling
Set agent_type: "code-agent" to use this agent type.

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Get your API key from https://lumo.starlight-search.com/dashboard

Body

application/json

Task configuration and parameters

​
task
string
required

The task description that the agent should complete. This can be a question, instruction, or complex multi-step task.

Example:

"What is the weather in Berlin?"

​
model
string
required

The AI model identifier to use for the task. This should match the model format expected by your base_url provider (e.g., OpenAI, Anthropic, etc.).

Example:

"gpt-4.1-nano"

​
base_url
string<uri>
required

The base URL for the chat completions API endpoint. This should point to your model provider's API.

Example:

"https://api.openai.com/v1/chat/completions"

​
tools
string[]

Array of tool identifiers available to the agent. The agent will automatically select and use these tools as needed to complete the task.

Example:
["ExaSearchTool", "VisitWebsite"]
​
max_steps
integer

Maximum number of steps the agent can take to complete the task. If not specified, the agent will continue until the task is completed or reaches a timeout.

Required range: x >= 1
Example:

3

​
agent_type
enum<string>
default:function-calling

Type of agent to use. 'function-calling' uses traditional function selection and execution. 'code-agent' uses executable Python code as actions, providing greater flexibility and efficiency for complex tasks. 'mcp' uses Model Context Protocol remote servers to connect to self-hosted toolchains.

Available options:
function-calling,
code-agent,
mcp
​
mcp_servers
object[]

Array of MCP remote server configurations. Required when agent_type is 'mcp'. Each server configuration specifies how to launch and connect to an MCP server.

Example:
[
  {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://mcp.linear.app/sse",
      "--header",
      "Authorization: Bearer ${AUTH_TOKEN}"
    ],
    "env": { "AUTH_TOKEN": "YOUR-AUTH_TOKEN" }
  }
]
​
messages
object[]

Optional conversation history or system messages. If not provided, the task will be treated as a standalone request.

Response

Task completed successfully

​
result
string

The final result or answer from the agent

​
steps
object[]

Array of steps taken by the agent to complete the task

​
tool_calls
object[]

Details of tool calls made during task execution

​
metadata
object

Additional metadata about the task execution