agent

Run an agent on a computer: OpenAI-shaped chat completions that drive the desktop

Changed on

Sends the conversation to a model that operates the computer named by computer_id (clicks, types, runs commands) until it answers. The request and response follow OpenAI chat completions, plus computer_id and an orgo block, so the OpenAI SDKs work with base URL https://www.orgo.ai/api/v1. messages[].content is a string or OpenAI content parts (text, and image_url as an https or base64 data URL in user messages). Roles other than user and assistant are dropped, and the first remaining message must be from the user. With stream: true the answer arrives as chat.completion.chunk Server-Sent Events ending in data: [DONE]; only text streams, and the thread id is in the X-Thread-Id header. A stream that ends without a chunk carrying a finish_reason failed: it ends with an error chunk (message, type, and code for a refused own key) before data: [DONE]. Closing the connection stops the run at its next step; steps already taken are billed.

A run takes up to 250 model steps. max_steps raises that, up to 500; it never lowers it. A run that reaches its limit finishes with finish_reason: "length".

Billed from AI credits by the workspace owner, unless you pay with your own model key: x-openai-key for a model OpenAI serves (orgo-agent, which runs GPT-6.1 Terra), x-anthropic-key for one Anthropic serves (the claude-* models and orgo-agent-opus-5.5). Then no credits are used, orgo.cost_cents is 0, and orgo.own_key says whose key paid. With no model, the key picks it: x-openai-key runs orgo-agent (also when you send both keys), x-anthropic-key alone runs claude-sonnet-5. On a computer orgo-agent does not run on, both keys run claude-sonnet-5 and x-openai-key alone is refused (400 own_key_unsupported). orgo-agent asks OpenAI for its fast tier, so OpenAI bills your key at its fast tier rates. A key that can't pay for the model you name is refused too (400 own_key_model_mismatch), so a request that sends a key is never billed to credits. When the provider turns your key down, the error says so: 401 invalid_own_key (a bad or unauthorized key), 429 own_key_rate_limited (its rate limit or quota), 400 own_key_model_unavailable (a model the key can't use). Keys are used for the request only, never stored.

post/api/v1/chat/completions

Request

  • Base URL
    https://www.orgo.ai
  • Auth
    HTTP bearer

Headers

x-openai-keystring

Your own OpenAI key. Pays for a model OpenAI serves (orgo-agent, GPT-6.1 Terra on OpenAI's fast tier), which then uses no credits. With no model, runs orgo-agent, and is refused (own_key_unsupported) when sent alone on a computer it does not run on. Refused for a model another provider serves (own_key_model_mismatch). Empty counts as not sent.

x-anthropic-keystring

Your own Anthropic key. Pays for a model Anthropic serves (the claude-* models, orgo-agent-opus-5.5), which then uses no credits. With no model and no x-openai-key, runs claude-sonnet-5. Refused for a model another provider serves (own_key_model_mismatch). Empty counts as not sent.

Request body

computer_idstring required

The computer to drive (its id, or its instance id, which changes when the computer wakes from storage; prefer the id). It must be running.

model'orgo-agent' | 'orgo-agent-opus-5.5' | 'claude-sonnet-5' | 'claude-opus-5.5' | 'claude-opus-5' | 'claude-opus-4.8' | 'claude-sonnet-4.6' | 'claude-opus-4.6'

Leave it out to get Orgo’s recommended engine for the computer and your key: orgo-agent (Computer Use) on Linux, Windows, macOS and iPhone computers with no key or with x-openai-key, Claude Sonnet 5 with only x-anthropic-key, or on other computers with no key or both keys (x-openai-key alone there is refused, own_key_unsupported). Name one to pin it. orgo-agent runs OpenAI’s GPT-6.1 Terra.

streamboolean
thread_idstring uuid

A thread to save this run to. It loads no history: send the whole conversation in messages every time, and the thread’s saved messages are replaced with them plus the reply. An unknown or non UUID id, a thread that isn’t yours, or, with a workspace scoped key, a thread on another computer starts a new thread.

max_stepsinteger

Raise the step limit. Lower values are treated as 250.

Response

The final answer. With stream: true, an event stream instead.

idstring
object'chat.completion'
createdinteger
modelstring
choicesobject[]

Changes

    • info

      added the new optional header request parameter x-openai-key

    • info

      added the non-success response with the status

    • info

      added the optional property / to the response with the status

    • info

      endpoint added