osAgents

DOCUMENTATION / OSAGENTS

Build an agent that keeps its context.

Get started

  1. Register with osFoundry ID and subscribe to Starter, Growth, or Sandbox.
  2. Connect and verify your BYOK model provider in Provider keys.
  3. Create an agent with instructions and a primary model in Agents.
  4. Create a server-side key in API keys. Never place it in a browser or repository.

Make a request

Use a unique Idempotency-Key for each new operation. Reuse the same key only to retry that exact operation.

curl https://api.osagents.app/api/v1/osagents/v1/messages \
  -H 'Authorization: Bearer YOUR_OSAGENTS_KEY' \
  -H 'Idempotency-Key: unique-operation-001' \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"YOUR_AGENT_ID","input":[{"role":"user","content":"Hello"}]}'

The response contains a response ID, status, output or required action, and usage when reported by the provider.

Server-managed conversations

Create a conversation with POST /v1/conversations using your key, Idempotency-Key, and {"agent_id":"YOUR_AGENT_ID","end_user_id":"customer-419","retention_days":7}. Retention may be 1, 7, or 30 idle days. Use the returned conv_… as conversation_id on later POST /v1/messages turns with the same agent and end user. osAgents carries recorded turns forward without resending the full chat. A plain session_id only scopes memory; it does not replay the whole transcript. See Conversations.

Runs and controls

Send Prefer: respond-async on a Messages request to receive a run ID while work continues. Inspect GET /v1/runs/{response_id} or the Runs page. Use POST /v1/runs/{response_id}/pause, /resume, or /cancel with an Idempotency-Key. Pausing or cancelling cannot undo an external operation already in flight. If a provider outcome is unknown after interruption, osAgents stops rather than blindly repeating a possibly billed call; it needs operator recovery after inspection and reconciliation. Each accepted continuation renews the response's 24-hour idle window.

Customer-hosted tools

Declare tools in a Messages request. When status is requires_action, validate required_action.tool_calls, execute approved actions in your application, and return one result per call to POST /v1/messages:

{"response_id":"resp_FROM_RESPONSE","tool_results":[{"tool_call_id":"toolu_FROM_RESPONSE","output":{"value":"done"}}]}

Use a fresh Idempotency-Key for the first continuation, then reuse it for exact retries. Customer-hosted tools remain under your application's control. If a model calls both a managed code tool and a customer-hosted tool in one turn, osAgents handles the managed call first and returns the customer call as a required action.

Files and skills

Files & skills lets you create versioned Markdown for startup context or on-demand use. Select an on-demand skill with skill_ids; runs pin file versions. GitHub Markdown import has preview and pinned-source confirmation. Review imported content: Markdown never grants execution permissions. A Markdown skill is an instruction, not executable code.

Managed code tools

Managed execution is available to active Sandbox subscribers. Starter and Growth cannot execute imported code. In the agent's Files & skills screen, open Code tools, enter a tool name and public GitHub repository, and preview the complete JavaScript source at a pinned commit. Importing creates a non-executable draft. A workspace owner must separately approve that exact version. Revoking a version prevents new runs from selecting it.

On an active Sandbox plan, a run pins approved versions and offers them to the model as osa_code_TOOL_NAME. osAgents executes a selected tool in a tenant-isolated, network-restricted runtime and returns its result to the same run. Do not place provider credentials in source or tool input: imported code does not receive provider keys or unrestricted network access. It is not an MCP server or a general-purpose internet-connected computer. Existing approved versions are pinned for an in-progress run, so review source and permissions before approval.

Each invocation has a deterministic job ID and an idempotency key. Exact retries return the recorded result. If the execution outcome is unknown, osAgents stops automatic retry to avoid repeating side effects; inspect the job and contact support before starting a new key. The execution budget is capped. An invocation counts at least one billed minute, rounded up from authoritative execution duration; the first 1,000 minutes are included in Sandbox.

Memory, retention, and deletion

osAgents selects bounded relevant memory scoped by workspace, agent, end user, and session; it does not send the whole memory store. Suggested lessons require approval in Reviews. Completed request content is not retained for dashboard inspection by default; an agent may opt into 24-hour inspection for future requests. Operational continuation state is separate. Conversation idle retention is 1, 7, or 30 days. Workspace export and deletion are in Settings; billing and minimal audit records may remain where required.

Usage and billing

Starter: $20/month, 10,000 runs, 1 GB memory, 5 concurrent provider calls. Growth: $59/month, 50,000 runs, 5 GB, 20 concurrent calls. Sandbox: $149/month, 50,000 runs, 5 GB memory, 20 concurrent provider calls, and 1,000 included execution minutes. Additional runs: $3 per 1,000; memory: $8 per GB-month; Sandbox execution: $0.20 per additional minute. Your BYOK provider bills inference separately. Input, cached, and output token usage appears only when reported; provider cost may be not reported, which is not zero. Starter and Growth include no sandbox minutes.