Models

All models are Pydantic BaseModel subclasses. Import from multirun.models.

from multirun.models import Run, Step, Budget, Checkpoint, Policy, Agent, AgentConfig

Run

RunStatus

class RunStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELLED = "cancelled"
    PAUSED = "paused"        # checkpointed, waiting for replay

Run

Represents a single agent execution.

Field	Type	Default	Description
`id`	`str`	auto UUID	Server-assigned run ID
`name`	`str`	`""`	Run name (e.g. `"research_agent"`)
`status`	`RunStatus`	`PENDING`	Current status
`parent_id`	`str \| None`	`None`	Parent run ID for sub-runs
`steps`	`list[Step]`	`[]`	Steps in this run
`current_step_id`	`str \| None`	`None`	Currently executing step
`checkpoints`	`list[CheckpointMeta]`	`[]`	Checkpoint metadata
`latest_checkpoint_id`	`str \| None`	`None`	Most recent checkpoint
`budget`	`Budget \| None`	`None`	Budget constraints
`tokens_used`	`int`	`0`	Total tokens consumed
`cost_usd`	`float`	`0.0`	Total cost
`policy`	`Policy \| None`	`None`	Policy rules
`metadata`	`dict[str, object]`	`{}`	User-defined metadata
`created_at`	`datetime`	now (UTC)	Creation timestamp
`started_at`	`datetime \| None`	`None`	When execution started
`completed_at`	`datetime \| None`	`None`	When execution ended
`result`	`bytes \| None`	`None`	Serialized return value
`error`	`str \| None`	`None`	Error message if failed

RunPatch

Partial update model. Only non-None fields are applied.

patch = RunPatch(status=RunStatus.COMPLETED, tokens_used=5000)

Step

StepKind

class StepKind(str, Enum):
    FUNCTION = "function"
    LLM_CALL = "llm_call"
    TOOL_CALL = "tool_call"
    SUB_AGENT = "sub_agent"
    DECISION = "decision"
    CHECKPOINT = "checkpoint"

StepStatus

class StepStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    SKIPPED = "skipped"      # during replay

Step

Atomic unit of execution within a run.

Field	Type	Default	Description
`id`	`str`	auto UUID	Step ID
`run_id`	`str`	`""`	Parent run ID
`agent_id`	`str`	`""`	Parent agent ID
`name`	`str`	`""`	Step name
`kind`	`StepKind`	`FUNCTION`	Type of step
`status`	`StepStatus`	`PENDING`	Current status
`parent_step_id`	`str \| None`	`None`	For nested steps
`input_hash`	`str`	`""`	SHA-256 of serialized input (replay key)
`input_data`	`bytes \| None`	`None`	Serialized input
`output_data`	`bytes \| None`	`None`	Serialized output
`policy_decision`	`str \| None`	`None`	`proceed`, `wait`, `fallback`, `abort`
`tokens_used`	`int`	`0`	Tokens consumed
`cost_usd`	`float`	`0.0`	Cost
`latency_ms`	`int`	`0`	Execution time
`started_at`	`datetime \| None`	`None`	Start time
`completed_at`	`datetime \| None`	`None`	End time
`error`	`str \| None`	`None`	Error if failed
`attempt`	`int`	`1`	Current retry attempt

Budget

Resource constraints for a run. All fields are optional — only set limits are enforced.

budget = Budget(
    max_tokens=100_000,
    max_cost_usd=1.0,
    max_steps=50,
    max_duration_seconds=300,
    max_sub_agents=5,
)

Field	Type	Description
`max_tokens`	`int \| None`	Maximum total tokens
`max_cost_usd`	`float \| None`	Maximum total cost in USD
`max_steps`	`int \| None`	Maximum number of steps
`max_duration_seconds`	`int \| None`	Maximum wall-clock time
`max_sub_agents`	`int \| None`	Maximum sub-agents

Methods

is_exceeded(run) -> bool — check if any limit is exceeded
get_exceeded_reason(run) -> str | None — human-readable reason

BudgetStatus

Current budget consumption snapshot.

Field	Type	Description
`tokens_used` / `tokens_remaining`	`int` / `int \| None`	Token usage
`cost_used_usd` / `cost_remaining_usd`	`float` / `float \| None`	Cost usage
`steps_used` / `steps_remaining`	`int` / `int \| None`	Step usage
`percentage_used`	`float`	Overall usage percentage
`is_exceeded`	`bool`	Whether any limit is exceeded

Checkpoint

Full checkpoint data for replay.

Field	Type	Description
`id`	`str`	Checkpoint ID
`run_id`	`str`	Parent run
`agent_id`	`str`	Parent agent
`step_id`	`str`	Checkpoint after this step
`name`	`str`	Checkpoint name
`state_data`	`bytes`	Serialized state blob
`state_format`	`str`	Serializer used (`cloudpickle`, `pickle`, `json`)
`context`	`dict`	JSON-serializable replay context
`environment`	`dict`	JSON-serializable environment info
`created_at`	`datetime`	Creation time
`size_bytes`	`int`	Size of `state_data`

CheckpointMeta

Lightweight metadata (no binary data). Used in Run.checkpoints list.

Field	Type	Description
`id`	`str`	Checkpoint ID
`run_id`	`str`	Parent run
`agent_id`	`str`	Parent agent
`step_id`	`str`	After this step
`name`	`str`	Checkpoint name
`created_at`	`datetime \| None`	Creation time
`size_bytes`	`int`	State size

Policy

PolicyDecision

class PolicyDecision(str, Enum):
    PROCEED = "proceed"
    WAIT = "wait"
    FALLBACK = "fallback"
    ABORT = "abort"

Policy

Collection of policy rules. All fields are optional.

from multirun.models import Policy
from multirun.models.policy import RetryRule, RateLimitRule, CircuitBreakerRule

policy = Policy(
    retry=RetryRule(max_attempts=3, backoff=BackoffStrategy.EXPONENTIAL),
    rate_limit=RateLimitRule(requests_per_minute=60),
    circuit_breaker=CircuitBreakerRule(failure_threshold=5, recovery_time_seconds=60),
)

Field	Type	Description
`budget`	`BudgetRule \| None`	Budget policy
`rate_limit`	`RateLimitRule \| None`	Rate limiting
`retry`	`RetryRule \| None`	Retry policy
`circuit_breaker`	`CircuitBreakerRule \| None`	Circuit breaker
`graceful_degradation`	`GracefulDegradationRule \| None`	Fallback to cheaper model

Policy rule types

BudgetRule — max_tokens, max_cost_usd
RateLimitRule — requests_per_minute, model
RetryRule — max_attempts, backoff (BackoffStrategy), base_delay_seconds, max_delay_seconds
CircuitBreakerRule — failure_threshold, recovery_time_seconds
GracefulDegradationRule — fallback_model, trigger (DegradationTrigger), threshold

Agent

AgentStatus

class AgentStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELLED = "cancelled"

Agent

Runtime agent instance within a run.

Field	Type	Description
`id`	`str`	Agent ID
`run_id`	`str`	Parent run
`agent_config_id`	`str \| None`	Reference to AgentConfig
`name`	`str`	Agent name
`status`	`AgentStatus`	Current status
`tokens_used`	`int`	Aggregated from steps
`cost_usd`	`float`	Aggregated from steps
`started_at` / `completed_at`	`datetime \| None`	Timing
`error`	`str \| None`	Error if failed
`metadata`	`dict \| None`	User-defined metadata

AgentConfig

Workspace-level reusable agent template.

Field	Type	Description
`id`	`str`	Config ID
`workspace_id`	`str`	Owning workspace
`name`	`str`	Template name
`description`	`str \| None`	Description
`config`	`dict`	Opaque config (model, tools, prompt, etc.)
`default_budget`	`Budget \| None`	Default budget for this agent type
`created_at` / `updated_at`	`datetime`	Timestamps

Models

On this page