Core Concepts

Core Concepts

AgentContainer is built around two core resources: Agents and Tasks. An agent defines the worker behavior and its pinned runtime. A task is one execution of that agent, either as a one-shot run or as a conversation that resumes across turns. Agents are versioned, so in-flight work is never disrupted by configuration changes.

Runtime

Every agent version owns a pinned runtime definition. That runtime describes what image and environment the agent runs inside: the base Docker image, installed tools, environment variables, and system-level configuration expected by the platform daemon.

In the public API, runtime is configured on the agent under a runtime object. It includes both the container image and the configured agent runtime.

"runtime": {
  "containerImage": "ghcr.io/acme/python-data-science:2026-03-30",
  "agentRuntime": "pi"
}

Runtime is part of agent versioning. If you change the image for an agent, you create a new agent version. Older tasks continue to use the exact runtime snapshot they were dispatched with.

AgentContainer uses pi as its agent runtime. Pi refers to Pi, the open source agent runtime.

Agents

An agent is a persistent configuration that defines a reusable worker. It owns its runtime image 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
• Agent runtime -- the execution harness, currently pi
• 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://agentcontainer.co/api/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",
  "runtime": {
    "containerImage": "ghcr.io/acme/pdf-runtime:2026-03-30",
    "agentRuntime": "pi"
  },
  "basePrompt": "You are a document analyst. Extract all tables and structured data from the provided files.",
  "defaults": {
    "model": "claude-sonnet-4.6",
    "internetAccess": false,
    "maxRuntimeSeconds": 1800,
    "outputPolicy": { "mode": "any" },
    "runtimeRegion": "any"
  }
}'

Agents are versioned. Updating any field -- the prompt, model, reference files, or runtime image -- 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 instructions and go. If you need to customize the prompt, model, or runtime image, fork a standard agent into your own custom agent and adjust from there. See the quickstart guide for a walkthrough.

Repositories

Reusable repositories let you define a git remote once, then attach it to agent versions or individual task runs. A repository can also store reusable tooling metadata such as a saved setup-script path and command aliases.

When you attach a repository, you choose which tag or branch to clone, where it should appear in the workspace, and whether a setup script should run before the agent starts. Attached repositories are cloned into the workspace before runtime startup.

Repository aliases expose executable files from that repository as command-line tools on the agent's PATH, which is useful for wrapper scripts, project-specific CLIs, and repeatable setup helpers.

Repository SSH keys are clone credentials only. Configure them on your git host as read-only deploy keys or equivalent least-privilege credentials. Do not attach writable user or machine credentials for repository cloning.

Even though private keys are never returned by the API, task execution happens in a shared task environment. A compromised task runtime could potentially recover daemon-side material, so writable repository credentials can turn a task compromise into repository modification or supply-chain risk.

Tasks

A task is a single unit of work dispatched to an agent. It can run in autonomous mode, where the agent works to completion, or in conversation mode, where you exchange messages with the same task over multiple turns. Autonomous tasks are created through the /tasks endpoint. Conversational tasks are created through the /conversations endpoint and still appear as task resources with mode: "conversation".

A task includes:

• Agent reference -- which agent (and optionally which version) to use
• Description -- the prompt written to ~/TASK.md inside the container
• Mode -- whether the task runs autonomously or as a conversational workflow
• 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, including its runtime image. Per-task overrides let you adjust settings for a single run without modifying the agent itself.

Provider and model combinations still matter. Anthropic, OpenRouter, and OpenAI models all run through the pi runtime.

curl -X POST https://agentcontainer.co/api/v1/agents/agt_xyz789/tasks \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "instructions": "Analyze the attached CSV and produce a summary report with charts.",
  "overrides": {
    "internetAccess": true,
    "maxRuntimeSeconds": 900
  }
}'

Task Lifecycle

Autonomous tasks and conversational tasks share the same task resource, but conversational tasks add one extra waiting state between turns.

Autonomous:     pending -> running -> finished
                                |-> failed
                                |-> cancelled

Conversation:   pending -> running -> awaiting_input -> running -> ...
                                |-> finished
                                |-> failed
                                |-> cancelled
                                |-> expired

• pending -- the task is queued and a container is being provisioned
• running -- the agent is actively working inside the container
• awaiting_input -- a conversational task has finished its current turn and is waiting for the next user message
• 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
• expired -- a conversational task sat idle past its session TTL

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

Versioning

Agents use an append-only versioning model. When you update an agent, the platform creates a new version and moves the currentVersionId pointer forward. Previous versions remain immutable and accessible.

Agent v1 ─────────────────────────────────────────
   |
   Task A (dispatched, uses Agent v1)

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

Agent v2 ─────────────────────────────────────────
   |
   Task B (dispatched, uses Agent v2)
   Task A continues running on Agent v1 (unaffected)

This design guarantees that editing an agent mid-run never changes behavior for in-flight tasks. Each task is pinned to the exact agent version that was current at dispatch time, including its runtime image.

curl -X PATCH https://agentcontainer.co/api/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 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 a standard agent directly: pick one, dispatch a task, and get results without configuring anything. When you need more control, fork a standard agent into your own account and customize its prompt, model, reference files, or runtime image.

curl -X POST https://agentcontainer.co/api/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:

Agent (worker configuration)
  └── Task (single execution)

Agent v2   defines runtime image, prompt, model, files, and policies
  └── Task inherits agent v2 and adds instructions, files, mode, and overrides

When you dispatch a task, the platform resolves the agent version, applies any per-task overrides, and provisions the container from that pinned runtime image. The result is a deterministic execution environment without making you manage containers directly.

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