OpenAI Agents SDK

The OpenAI Agents SDK (Python and TypeScript) runs on Magmell against your own provider endpoint. Magmell certifies one logical agent run with one final output — the command deployment contract — in both runtimes, with runnable examples in the repository under examples/agent-frameworks/openai-agents.

What is certified

One agent run that ends in a single final output, on python-3.12 and node-22.
A custom provider (custom base_url/baseURL and API key), which Magmell supplies as environment variables.
One client-executed stdio MCP tool inside that run (it runs in your process, not a Magmell-hosted MCP).

Streaming run responses, persistent sessions, resume, and human-in-the-loop are not part of the one-shot contract. Client-executed Streamable HTTP MCP works as ordinary customer networking but is not certified per framework. The Claude Agent SDK runs as a generic command with no provider-independence claim; Mistral-specific integration is out of scope.

Configure the provider

Point the SDK at your endpoint with the standard environment variables and disable trace export — otherwise the SDK tries to POST traces to OpenAI, which a custom provider neither wants nor authorizes. Set OPENAI_BASE_URL and OPENAI_API_KEY as secrets on the deployment.

Python

import os
from agents import Agent, OpenAIChatCompletionsModel, Runner, set_tracing_disabled
from openai import AsyncOpenAI

set_tracing_disabled(True)
client = AsyncOpenAI(base_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"])
agent = Agent(
    name="assistant",
    instructions="You are a concise assistant.",
    model=OpenAIChatCompletionsModel(model="your-model", openai_client=client),
)
result = await Runner.run(agent, "your prompt")
print(result.final_output)

TypeScript

import { Agent, OpenAIProvider, run, setDefaultModelProvider, setTracingDisabled } from '@openai/agents'

setTracingDisabled(true)
setDefaultModelProvider(
  new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: process.env.OPENAI_BASE_URL,
    useResponses: false,
  }),
)
const agent = new Agent({ name: 'assistant', instructions: 'You are a concise assistant.', model: 'your-model' })
const result = await run(agent, 'your prompt')
console.log(result.finalOutput)

useResponses: false selects the Chat Completions API, which most custom providers implement.

Reasoning models: use the Responses API

Chat Completions is the safe default for custom providers, but it often does not work with a reasoning model (for example the gpt-5 family) that also calls tools: many providers reject function tools combined with a reasoning effort on /v1/chat/completions and direct you to /v1/responses. When that happens, select the Responses API instead.

Python

from agents import Agent, OpenAIResponsesModel

model = OpenAIResponsesModel(model="your-reasoning-model", openai_client=client)
agent = Agent(name="assistant", instructions="…", model=model, tools=[...])

TypeScript

new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY, baseURL: process.env.OPENAI_BASE_URL, useResponses: true })

If your provider only implements Chat Completions, keep Chat Completions and either use a non-reasoning model or call the reasoning model without function tools.

Function tools and sub-agents

Within one run your agent can do anything your code can: the command executes as an ordinary process in an isolated sandbox, so the SDK’s full local surface is available.

Function tools (@function_tool in Python, tool() in TypeScript) that do real work — read and write files, run shell commands, call an HTTP API.
Sub-agents exposed as tools with Agent.as_tool(...), so an orchestrator can delegate to a specialist agent.
A client-executed stdio MCP server launched as a child of the run.

These are your code running in the sandbox, not a Magmell-hosted feature, so they stay inside the one-shot contract: one logical run, one final output, the run deadline, and the 1 MiB stdout result bound. Use the Responses API (above) when a reasoning model drives the tools.

from agents import Agent, function_tool

@function_tool
def run_shell(command: str) -> str:
    "Run a shell command in the workspace and return its output."
    ...

coder = Agent(name="coder", instructions="Write a small Python script.", model=model)
orchestrator = Agent(
    name="orchestrator",
    instructions="Use the tools to do real work, then report what you did.",
    model=model,
    tools=[run_shell, coder.as_tool(tool_name="coder", tool_description="Delegate writing code.")],
)

The same shape in TypeScript — tool() for a function tool and agent.asTool() for a sub-agent, with the Responses provider set as the default (above):

import { Agent, tool } from '@openai/agents'
import { z } from 'zod'

const runShell = tool({
  name: 'run_shell',
  description: 'Run a shell command in the workspace and return its output.',
  parameters: z.object({ command: z.string() }),
  execute: async ({ command }) => '…run it, return the output…',
})

const coder = new Agent({ name: 'coder', instructions: 'Write a small script.', model: 'your-reasoning-model' })
const orchestrator = new Agent({
  name: 'orchestrator',
  instructions: 'Use the tools to do real work, then report what you did.',
  model: 'your-reasoning-model',
  tools: [runShell, coder.asTool({ toolName: 'coder', toolDescription: 'Delegate writing code.' })],
})

The python/command_tools.py example spawns a coder sub-agent, writes a script to disk, runs it, and reports the output — over the Responses API — so it needs a real reasoning-capable provider (it is not part of the loopback smoke test that certifies command.py). The TypeScript API is identical in shape; only the Python example ships as a file.

Deploy as a command

A one-shot command reads the run input on stdin and prints the final output; deploy it with the command preset. Node command deployments run precompiled JavaScript — commit dist/ and point the entrypoint at it.

# Python
magmell deploy ./python --name oa --version 1 \
  --preset command --entrypoint python --entrypoint command.py

# TypeScript
magmell deploy ./typescript --name oa-ts --version 1 --runtime node-22 \
  --preset command --entrypoint node --entrypoint dist/command.js

You can also deploy the SDK program under the default handler preset (a handle function that runs the agent and returns its output). See command deployments for the full runtime contract, and errors and limits for command failure categories.