Skip to main content

​
Running Agents

The run_agent function executes agents in isolated Docker containers.

​
Basic Usage

from plato.agents import run_agent

await run_agent(
    image="my-agent:latest",
    config={"model_name": "claude-sonnet-4"},
    secrets={"anthropic_api_key": "sk-..."},
    instruction="Fix the bug in main.py",
    workspace="/path/to/workspace",
)

​
Parameters

ParameterTypeRequiredDescription
imagestrYesDocker image URI
configdictYesAgent configuration
secretsdict[str, str]YesSecrets as env vars
instructionstrYesTask instruction
workspacestrYesMounted workspace path
logs_dirstr | NoneNoLogs directory
pullboolNoPull image first (default: True)

​
Volume Mounts

Container PathHost PathDescription
/workspaceworkspace paramAgent working directory
/logslogs_dir paramLogs and trajectory output
/config.json(temp file)Agent configuration

​
Secret Injection

Secrets become environment variables: 
secrets = {
    "anthropic_api_key": "sk-...",
    "git_token": "ghp_...",
}

# In container:
# ANTHROPIC_API_KEY=sk-...
# GIT_TOKEN=ghp_...

​
Example: From a World

from plato.agents import run_agent
from plato.worlds import BaseWorld, StepResult

class MyWorld(BaseWorld[MyWorldConfig]):
    async def step(self) -> StepResult:
        agent = self.config.coder

        await run_agent(
            image=agent.image,
            config=agent.config,
            secrets=self.config.all_secrets,
            instruction=self.config.prompt,
            workspace="/workspace",
            logs_dir="/workspace/.agent_logs",
            pull=False,
        )

        return StepResult(
            observation=Observation(data={"completed": True}),
            done=True,
        )

​
Example: Standalone

import asyncio
import os
from plato.agents import run_agent

async def main():
    await run_agent(
        image="383806609161.dkr.ecr.us-west-1.amazonaws.com/agents/openhands:1.0.0",
        config={
            "model_name": "anthropic/claude-sonnet-4",
            "max_iterations": 50,
        },
        secrets={
            "anthropic_api_key": os.environ["ANTHROPIC_API_KEY"],
        },
        instruction="Create a fibonacci function",
        workspace="/tmp/workspace",
        logs_dir="/tmp/logs",
    )

asyncio.run(main())

​
Error Handling

try:
    await run_agent(...)
except RuntimeError as e:
    print(f"Agent failed: {e}")

​
Trajectory Output

Agents write trajectories to /logs/agent/trajectory.json: 
{
  "schema_version": "1.0.0",
  "agent": {
    "name": "my-agent",
    "version": "1.0.0"
  },
  "steps": [...]
}