Agents API
De Agents API geeft uw applicatie toegang tot de Codex-harness via een door OpenAI beheerde API. OpenAI beheert sessies, orchestratie, context-compressie en herstel, terwijl uw applicatie de tools levert en de executieomgeving kiest. Agents kunnen werken in een sandbox waar ze code kunnen uitvoeren, bestanden kunnen bewerken, kunnen verbinden met MCP-servers en artefacten kunnen produceren.
Prijsstelling
Het gebruik van modellen wordt gefactureerd volgens de API-tarieven van het geselecteerde model. OpenAI-tools gebruiken hun standaardtarieven en door OpenAI beheerde sandboxes maken gebruik van de standaard container-tarieven.
Voorbeelden
Complete voorbeelden
- Creëer en voer een script uit voor een mappenstructuur in een door OpenAI beheerde sandbox.
- Vergelijk release-notities met subagents en combineer hun bevindingen in één antwoord.
Complete applicaties
- Incident response agent: Onderzoek meldingen en vraag goedkeuring aan voor herstelacties.
- Slack bot: Onderzoek verzoeken met behulp van verbonden werkplek-tools.
- Data-analist: Beantwoord vragen over het datawarehouse met read-only SQL.
- GitHub issue investigator: Reproduceer gemelde bugs en deel de bevindingen op GitHub.
- Document reviewer: Beoordeel documenten met beleidsskills en gespecialiseerde agents.
Kernconcepten
De Agents API is gebouwd rond vier hoofdconcepten:
- Agent: Het model, de instructies, de tools en de MCP-servers die beschikbaar zijn voor de agent.
- Environment (Omgeving): Een optionele sandbox of computer waar de agent toegang heeft tot bestanden, skills laadt en commando's uitvoert.
- Session (Sessie): Een duurzame instantie van een agent die werkt aan taken en reageert op input.
- Events and items (Events en items): De inputs die naar een agent worden gestuurd en de output die tijdens een sessie wordt geproduceerd.
Een sessie van begin tot eind
Indien u start met een door OpenAI beheerde sandbox in de quickstart, verloopt het proces als volgt:
- Create a session: Maak een sessie aan. Configureer de agent; OpenAI voorziet in de omgeving.
- Give it a task: Geef de agent een taak. Gebruikersinput start een beurt van werk zodra de omgeving gereed is.
- Follow progress: Volg de voortgang. Stream de output of gebruik webhooks om te weten wanneer de agent klaar is of input nodig heeft.
- Continue or steer: Stuur een nieuwe taak naar dezelfde sessie, of stuur de agent bij tijdens de huidige beurt.
Bij een door OpenAI beheerde sessie verzendt uw applicatie input en ontvangt deze events, terwijl OpenAI de agent uitvoert en de sandbox voorziet en beheert.
Wat de beheerde harness biedt
De beheerde Codex-harness ondersteunt:
- Het uitvoeren van commando's en code in een sandbox.
- Het toepassen van relevante skills en instructies.
- Verbinding maken met externe data via tools of MCP.
- Het bijsturen van de agent terwijl deze werkt.
- Het samenvatten van eerder werk om het contextvenster te beheren.
- Het opdelen van werk in subtaken en het delegeren hiervan aan subagents.
- Het hervatten van een sessie waar deze was gebleven.
Configuratie van managed-harness mogelijkheden
Hieronder staan voorbeelden van hoe u deze mogelijkheden configureert bij het aanmaken van een sessie:
Python
from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
"tools": [
{"type": "programmatic_tool_calling"},
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp",
},
},
{"type": "web_search"},
],
"multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
},
environment={
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": ["/workspace/capabilities/skills"],
},
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
}
],
}
],
)
print(session.id)Node.js
import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions:
"Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
tools: [
{ type: "programmatic_tool_calling" },
{
type: "mcp",
server_label: "openai_docs",
transport: {
type: "http",
server_url: "https://developers.openai.com/mcp",
},
},
{ type: "web_search" },
],
multi_agent: { enabled: true, max_concurrent_subagents: 4 },
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/capabilities/skills"],
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
},
],
},
],
});
console.log(session.id);Go
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
Tools: []openai.AgentToolParamUnion{
openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{
ServerLabel: "openai_docs",
Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}},
}},
openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}},
},
MultiAgent: openai.MultiAgentConfigParam{
Enabled: true,
MaxConcurrentSubagents: openai.Int(4),
},
},
Environment: openai.EnvironmentParamUnion{
OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{
WorkspaceDirectory: "/workspace",
CapabilityDirectories: []string{"/workspace/capabilities/skills"},
},
},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
openai.AgentSessionInputMessageParam{
Content: []openai.InputContentParamUnion{
openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}},
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(session.ID)Java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions(
"Use the OpenAI documentation MCP and web search to answer"
+ " technical questions accurately. Delegate independent"
+ " research tasks to subagents when useful.")
.addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
.addTool(
AgentToolParam.Mcp.builder()
.serverLabel("openai_docs")
.transport(
McpTransportParam.Http.builder()
.serverUrl("https://developers.openai.com/mcp")
.build())
.build())
.addTool(AgentToolParam.WebSearch.builder().build())
.multiAgent(
MultiAgentConfigParam.builder()
.enabled(true)
.maxConcurrentSubagents(4L)
.build())
.build())
.environment(
EnvironmentParam.SelfHosted.builder()
.workspaceDirectory("/workspace")
.capabilityDirectories(List.of("/workspace/capabilities/skills"))
.build())
.input(
"Research how to connect an MCP server to an OpenAI agent, check for recent"
+ " updates, and summarize the recommended setup.")
.build());
System.out.println(session.id());Ruby
require "openai"
client = OpenAI::Client.new
session = client.beta.agents.sessions.create(
agent: {
model: "gpt-6-astra",
instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
tools: [
{type: "programmatic_tool_calling"},
{
type: "mcp",
server_label: "openai_docs",
transport: {type: "http", server_url: "https://developers.openai.com/mcp"}
},
{type: "web_search"}
],
multi_agent: {enabled: true, max_concurrent_subagents: 4}
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/capabilities/skills"]
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
}
]
}
]
)
puts session.idcURL
curl -sS -X POST "https://api.openai.com/v1/agents/sessions" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
"tools": [
{
"type": "programmatic_tool_calling"
},
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp"
}
},
{
"type": "web_search"
}
],
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 4
}
},
"environment": {
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": ["/workspace/capabilities/skills"]
},
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
}
]
}
]
}'Sessiestatus en Gegevensresidentie
De Agents API behoudt de sessiestatus, zodat u het werk over verschillende beurten heen kunt voortzetten zonder de gesprekcontext opnieuw op te bouwen. U kunt sessies en gepubliceerde artefacten verwijderen wanneer u deze niet meer nodig heeft.
De Agents API ondersteunt momenteel gegevensresidentie alleen in de Verenigde Staten en ondersteunt geen Zero Data Retention (ZDR). Het kiezen van een zelfgehoste sandbox maakt de Agents API niet in aanmerking voor ZDR.
Groetjes,