OpenAI's response to the persistent failures of long-running AI agents is a set of three connected primitives: Skills, a hosted shell tool, and server-side compaction. By the end of this guide you will understand what each primitive does, why it matters, and how to start building with them.
Table of Contents
- Why Long-Running Agents Keep Failing
- What Are Agentic Primitives (And Why Do They Matter)?
- Skills: Reusable Instructions Your Agent Can Actually Follow
- The Upgraded Shell Tool: A Safe Place for Agents to Work
- Server-Side Compaction: Never Hit Context Limits Again
- Putting It All Together: A Complete Agent Loop
- Practical Tips and Gotchas
- What This Means for the Future of AI Agents
Why Long-Running Agents Keep Failing
If you have tried building an AI agent that does real, sustained work, you already know the frustration. The OpenAI agentic primitives announced alongside the Responses API target three specific failure modes that plague every developer who moves beyond simple chat completions. First, agents lose track of what they are supposed to do. Instructions pasted into system prompts are fragile, non-portable, and easily overridden by long conversation histories. Second, agents have no safe place to actually execute code. They can suggest a script, but running it, installing dependencies, and returning artifacts requires external infrastructure that most teams cobble together themselves. Third, long-running agent loops burn through context windows fast. A complex agentic workflow can exhaust the context limit in minutes, and once you hit that ceiling, the session is effectively dead.
OpenAI's response is a set of three connected primitives: Skills, a hosted shell tool, and server-side compaction. Each one addresses a specific failure mode, and together they form a unified server-side stack for agents that need to do multi-step, sustained work. By the end of this guide you will understand what each primitive does, why it matters, and how to start building with them.
A complex agentic workflow can exhaust the context limit in minutes, and once you hit that ceiling, the session is effectively dead.
What Are Agentic Primitives (And Why Do They Matter)?
"Agentic primitives" is OpenAI's term for the foundational building blocks that let developers construct agents capable of real, ongoing work rather than one-shot question-and-answer exchanges. Think of them as low-level capabilities you compose into higher-level agent behavior, much like system calls form the foundation of an operating system.
These primitives did not emerge from a whiteboard exercise. OpenAI developed them while building Codex and other internal agents, encountering the same reliability, execution, and context management problems that external developers face. The Responses API (POST /v1/responses) is the unified surface through which all three primitives are accessed. Rather than being isolated features bolted onto a chat endpoint, Skills, the shell tool, and compaction are designed to work as a system: skills define what the agent should do, the shell gives it a place to do it, and compaction ensures the agent can keep doing it for as long as necessary.
Skills: Reusable Instructions Your Agent Can Actually Follow
What Are Skills?
Skills are reusable, versioned sets of instructions that you attach to an agent's context. If system prompts are sticky notes, skills are formal recipe cards: structured, portable, and version-controlled. Each skill has a name, a version identifier, a description, and a set of instructions the agent follows when the skill is invoked.
Critically, OpenAI's implementation draws on the concept of an open Agent Skills standard. However, this specification is still nascent and its adoption across other platforms is not yet widespread. The goal is that skill definitions would not be locked into OpenAI's ecosystem, allowing any framework or platform that adopts the same spec to consume and produce compatible skills, giving developers portability across toolchains.
Why Skills Solve the Reliability Problem
Without skills, developers cram behavioral instructions into the system prompt or scatter them across tool descriptions. This approach is brittle: one long user message can push instructions out of the model's attention window, and there is no clean way to version or share those instructions across projects. With skills, instructions are structured objects that the API treats as first-class entities. They are composable (you can mount several small skills rather than one monolithic prompt), versionable (you can pin to v1.0 while developing v1.1), and standardized (other developers can read, audit, and reuse them).
If system prompts are sticky notes, skills are formal recipe cards: structured, portable, and version-controlled.
Your First Skill Definition
Below is a simple skill definition following a JSON format, then a Python snippet that mounts it into a Responses API call:
from openai import OpenAI
# Requires: pip install openai>=1.14.0
# Ensure OPENAI_API_KEY is set in your environment
client = OpenAI()
# Define a skill inline (could also be loaded from a file or registry)
data_analysis_skill = {
"name": "csv_summarizer",
"version": "1.0.0",
"description": "Analyzes a CSV file and produces a Markdown summary report.",
"instructions": (
"1. Read the provided CSV data.\n"
"2. Identify column types and compute descriptive statistics.\n"
"3. Highlight any missing values or anomalies.\n"
"4. Return a concise Markdown report with tables for key metrics."
)
}
response = client.responses.create(
model="gpt-4o",
instructions=data_analysis_skill["instructions"],
input=[
{"role": "user", "content": "Summarize the attached sales data."}
],
metadata={
"skill_name": data_analysis_skill["name"],
"skill_version": data_analysis_skill["version"]
}
)
print(response.output_text)The metadata fields let you track which skill version produced each response, making debugging and iteration straightforward.
The Upgraded Shell Tool: A Safe Place for Agents to Work
What Is the Hosted Shell?
The hosted shell is an OpenAI-managed container environment where agents can install dependencies, execute scripts, manipulate files, and produce artifacts. It builds on the earlier code interpreter tool (which was limited to a sandboxed Python runtime) by providing a more complete environment with controlled internet access. Agents can fetch packages from registries and pull data from approved external sources, but network access operates within guardrails to prevent arbitrary egress. Note that the exact capabilities and degree of network access may vary as OpenAI continues to develop this feature.
What Agents Can Do in the Shell
The practical capabilities cover the tasks most agent workflows actually need. Agents can install packages via pip, npm, or apt (depending on the container configuration). They can run multi-step shell scripts that chain commands together. They can write files and return them as artifacts, whether that is a generated PDF report, a transformed CSV, or other output files. Example use cases include data analysis pipelines, code generation followed by automated testing, and document generation workflows.
Using the Shell Tool in the Responses API
Here is a Python example that enables the shell tool and asks the agent to process a CSV:
from openai import OpenAI
# Requires: pip install openai>=1.14.0
# Ensure OPENAI_API_KEY is set in your environment
client = OpenAI()
response = client.responses.create(
model="gpt-4o",
tools=[
{
"type": "code_interpreter", # shell-capable environment
}
],
input=[
{
"role": "user",
"content": (
"Install pandas, then load the file sales_q1.csv, "
"compute monthly revenue totals, and return the result "
"as a Markdown summary."
)
}
]
)
# Iterate through output items for text and file artifacts
for item in response.output:
if item.type == "text":
print(item.text)
elif hasattr(item, "content"):
# code_interpreter results may include nested content
for block in item.content:
if hasattr(block, "text"):
print(block.text)The response structure includes both text output and file references. You can retrieve file artifacts via the Files API endpoint using the returned file ID.
Server-Side Compaction: Never Hit Context Limits Again
The Context Window Problem
Every message, tool call, and tool output in an agent loop consumes tokens. A single shell execution that returns a large log or data dump can eat thousands of tokens in one step. Once the conversation history approaches the model's context limit, you face an ugly choice: manually truncate messages (risking loss of critical context), summarize on the client side (adding complexity and latency), or restart the session entirely.
How Compaction Works
Server-side compaction shifts this burden to the API. When enabled, the Responses API automatically truncates older portions of the conversation history during long-running sessions to keep the input within the model's context window. The model retains the most recent and most relevant information, such as the current task, key findings, and active instructions, while dropping older messages that no longer fit. This happens transparently; your client code continues to send and receive messages without managing a sliding window. It is important to understand that this is truncation-based rather than a lossless summarization—older context is removed, not perfectly condensed.
Server-side compaction shifts this burden to the API. When enabled, the Responses API automatically truncates older portions of the conversation history during long-running sessions to keep the input within the model's context window.
Enabling Compaction
Enabling compaction is a single parameter on your API call:
from openai import OpenAI
# Requires: pip install openai>=1.14.0
# Ensure OPENAI_API_KEY is set in your environment
client = OpenAI()
response = client.responses.create(
model="gpt-4o",
input=[
{"role": "user", "content": "Begin the multi-step analysis workflow."}
],
tools=[{"type": "code_interpreter"}],
truncation="auto" # Enables server-side compaction
)
# Usage stats show token accounting post-compaction
print(f"Input tokens used: {response.usage.input_tokens}")
print(f"Output tokens used: {response.usage.output_tokens}")The truncation parameter set to "auto" tells the API to manage context automatically. You can inspect response.usage to monitor token consumption and verify that truncation is keeping your sessions within bounds.
Putting It All Together: A Complete Agent Loop
Architecture of a Long-Running Agent
The three primitives connect in a natural pipeline. A skill defines the agent's instructions and behavioral contract. The shell provides the execution environment for carrying out those instructions. Compaction ensures the loop can run for extended periods without running out of context. The flow looks like this:
Skill mounted → Agent receives task → Shell executes steps → Compaction manages context → Agent returns artifact
End-to-End Example
Here is a complete script that combines all three primitives. The agent researches a topic using shell tools, writes a Markdown report, and returns it as an artifact:
from openai import OpenAI
# Requires: pip install openai>=1.14.0
# Ensure OPENAI_API_KEY is set in your environment
client = OpenAI()
# 1. Define and reference a skill
research_skill = {
"name": "topic_researcher",
"version": "1.0.0",
"instructions": (
"You are a research agent. Given a topic:\n"
"1. Gather key facts using available tools.\n"
"2. Organize findings into sections.\n"
"3. Write a polished Markdown report.\n"
"4. Save the report as report.md and return it."
)
}
# 2. Create the response with shell tool + compaction
response = client.responses.create(
model="gpt-4o",
instructions=research_skill["instructions"],
tools=[
{"type": "code_interpreter"}
],
input=[
{
"role": "user",
"content": (
"Research the current state of battery recycling technology. "
"Write a 500-word Markdown report and save it as report.md."
)
}
],
truncation="auto", # 3. Enable compaction for long runs
metadata={
"skill_name": research_skill["name"],
"skill_version": research_skill["version"]
}
)
# 4. Process outputs
for item in response.output:
if item.type == "text":
print(item.text)
elif hasattr(item, "content"):
for block in item.content:
if hasattr(block, "text"):
print(block.text)
print(
f"\nTokens used — input: {response.usage.input_tokens}, "
f"output: {response.usage.output_tokens}"
)This single script demonstrates the full lifecycle: structured skill instructions govern behavior, the shell executes the research and writing steps, and compaction ensures the session stays within token limits regardless of how many intermediate steps the agent takes.
Practical Tips and Gotchas
Best Practices
Version your skills from the start, even if you are iterating quickly. Small, single-purpose skills compose better than large monolithic instruction sets. Do not assume shell state persists across separate API calls; treat each response as potentially starting from a clean environment unless you are explicitly using session continuity features. During development, log response.usage on every call to understand how truncation affects your token budget.
Current Limitations
Shell containers have resource and time limits; extremely long-running computations may be terminated. Truncation is lossy by nature. It works well for maintaining recent task context, but if your workflow requires perfect recall of every prior message (audit trails, legal compliance), you should archive the full transcript client-side. The Agent Skills open standard is still evolving, so expect changes to the spec as it matures. Finally, be mindful of security: if your shell agent installs packages from public registries, supply-chain risks apply. Also note that these features are relatively new and their exact API surface, parameter names, and behavior may change as OpenAI iterates—always consult the latest API reference documentation.
These primitives represent a clear shift from the "chatbot" paradigm to the "worker" paradigm.
What This Means for the Future of AI Agents
These primitives represent a clear shift from the "chatbot" paradigm to the "worker" paradigm. OpenAI is packaging the infrastructure agents need to do sustained, autonomous work as first-class API features rather than leaving developers to build that scaffolding themselves. The fact that OpenAI has signaled interest in an open skills specification suggests a bet on interoperability rather than vendor lock-in. For developers just getting started with agent development, the tooling has finally caught up to the ambition. Now is the time to start building.