Core Concepts

Core Concepts

AgentContainer is built around three primitives: Containers, Agents, and Tasks. Each layer builds on the one below it. A container defines the execution environment, an agent defines the worker configuration that runs inside that environment, and a task is a single unit of work dispatched to an agent. Both containers and agents are versioned, so in-flight work is never disrupted by configuration changes.

Containers

A container is a persistent, reusable execution environment definition. It describes what image and environment an agent runs inside -- the base Docker image, installed tools, environment variables, and system-level configuration. Containers do not run on their own; they are referenced by agents.

Every container has a name, an optional description, and either a preset (platform-managed image) or a custom image reference.

curl -X POST https://api.agentcontainer.com/v1/containers \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "python-data-science",
  "description": "Python 3.12 with pandas, numpy, and matplotlib",
  "preset": "data-processing"
}'

Containers are versioned. Every time you update a container -- changing the image, adding environment variables, adjusting installed packages -- a new version is created. Agents point at a specific container version, so editing a container never silently changes an agent that is already running.

Standard Containers

The platform ships a set of standard containers for common workloads: general-purpose coding, document analysis, and data processing. These are maintained by the AgentContainer team and kept up to date with the latest tooling. You can use a standard container directly, or fork it into your own custom container to add packages, change environment variables, or swap the base image.

Agents

An agent is a persistent configuration that defines a reusable worker. It references a container (the environment it runs inside) and layers on everything the model needs to do its job: a base prompt, a default model, reference files, and runtime policies.

An agent's configuration includes:

• Name and description -- human-readable identifiers
• Base prompt -- the system-level instructions given to the model on every task
• Default model -- e.g. claude-sonnet-4.6
• Reference files -- documents and PDFs that are always available inside the container
• Default internet access -- whether the container can reach the public internet
• Default max runtime -- the timeout ceiling for each task
• Output policy -- rules governing what the agent produces and returns

curl -X POST https://api.agentcontainer.com/v1/agents \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "pdf-analyst",
  "description": "Extracts tables and key data from uploaded PDFs",
  "containerId": "ctr_abc123",
  "basePrompt": "You are a document analyst. Extract all tables and structured data from the provided files.",
  "model": "claude-sonnet-4.6",
  "internetAccess": false,
  "maxRuntimeMinutes": 30
}'

Like containers, agents are versioned. Updating any field -- the prompt, model, reference files, or the container reference -- creates a new agent version. Tasks dispatched after the update use the new version, while in-flight tasks continue on the version they were dispatched with.

Standard Agents

Standard agents are platform-provided and ready to use out of the box. They let you dispatch tasks immediately without any setup -- just provide a description and go. If you need to customize the prompt, model, or container, fork a standard agent into your own custom agent and adjust from there. See the quickstart guide for a walkthrough.

Tasks

A task is a single unit of work dispatched to an agent. When you create a task, the platform spins up a fresh container from the agent's pinned container version, injects the agent's configuration, writes your task description to ~/TASK.md, and starts the model.

A task includes:

• Agent reference -- which agent (and optionally which version) to use
• Description -- the prompt written to ~/TASK.md inside the container
• Input files -- files uploaded and made available in the working directory
• Per-task overrides -- optional overrides for model, internet access, max runtime, and output policy

Tasks inherit everything from the pinned agent version, which in turn inherits the pinned container version. Per-task overrides let you adjust settings for a single run without modifying the agent itself.

curl -X POST https://api.agentcontainer.com/v1/tasks \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "agt_xyz789",
  "description": "Analyze the attached CSV and produce a summary report with charts.",
  "internetAccess": true,
  "maxRuntimeMinutes": 15
}'

Task Lifecycle

Every task moves through a simple state machine:

pending ──> running ──> finished
                  |──> failed
                  |──> cancelled

• pending -- the task is queued and a container is being provisioned
• running -- the agent is actively working inside the container
• finished -- the agent completed successfully and output files are available
• failed -- the task hit an unrecoverable error or exceeded its max runtime
• cancelled -- the task was cancelled by the user before completion

For details on retrieving output files and streaming logs, see the Tasks and Output guide.

Versioning

Both containers and agents use an append-only versioning model. When you update either resource, the platform creates a new version and moves the currentVersionId pointer forward. The previous versions remain immutable and accessible.

Container v1 ─────────────────────────────────────
                  \
Agent v1 ──────────> points at Container v1
                      |
                      Task A (dispatched, uses Agent v1 + Container v1)

--- you update the agent's prompt ---

Agent v2 ──────────> still points at Container v1
                      |
                      Task B (dispatched, uses Agent v2 + Container v1)
                      Task A continues running on Agent v1 (unaffected)

This design guarantees that editing a container or agent mid-run never changes behavior for in-flight tasks. Each task is pinned to the exact agent version (and through it, the exact container version) that was current at dispatch time.

curl -X PATCH https://api.agentcontainer.com/v1/agents/agt_xyz789 \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "basePrompt": "You are a senior document analyst. Extract all tables, charts, and key metrics.",
  "model": "claude-opus-4-20250514"
}'

{
  "id": "agt_xyz789",
  "name": "pdf-analyst",
  "currentVersionId": "agv_002",
  "previousVersionId": "agv_001",
  "updatedAt": "2026-03-26T14:30:00Z"
}

Standard vs Custom

AgentContainer provides standard containers and standard agents as platform-maintained starting points. These cover common use cases out of the box -- general-purpose coding, document analysis, data processing -- and are kept up to date by the AgentContainer team.

You can use standard resources directly: pick a standard agent, dispatch a task, and get results without configuring anything. When you need more control, fork a standard resource into a custom one. Forking copies the current configuration into your own account, giving you full control to change the prompt, swap the model, add reference files, or modify the container environment.

curl -X POST https://api.agentcontainer.com/v1/agents/agt_standard_coding/fork \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-coding-agent",
  "basePrompt": "You are a senior TypeScript developer. Always use strict mode and write tests."
}'

The forked agent is fully independent. Updates to the original standard agent do not propagate to your fork. You can continue to customize it freely, and it follows the same versioning rules as any other agent.

Putting It Together

The full inheritance chain looks like this:

Container (environment)
  └── Agent (worker configuration)
        └── Task (single unit of work)

Container v3          defines the runtime image and tools
  └── Agent v2        adds prompt, model, reference files, policies
        └── Task      inherits agent v2 + container v3, adds description + input files

When you dispatch a task, the platform resolves the full chain: it looks up the agent's current version, then that version's pinned container version, merges in any per-task overrides, and provisions the container. The result is a fully deterministic, reproducible execution environment.

For a hands-on walkthrough, head to the Quickstart guide. For the full list of API endpoints, see the API Reference.