01 Minimal agent

Before you start

You should have the Python SDK installed (Install and build) and have read 03 Anatomy of a workflow. That page explains how a Workflow holds steps and how run(input) produces result.output. Here we focus on the object each step references: the Agent.

Concept

An agent is a definition, not a running process. You describe who the agent is and what it should do; the ArcFlow runtime executes that definition when the workflow reaches the step that references it.

The Python constructor requires three strings:

Empty strings are rejected at construction time with WorkflowConfigurationError. The runtime assigns a UUID internally; you do not need to pass an id for local scripts.

With no provider configured, the stub runtime returns deterministic placeholder text. That is enough to confirm your agent wiring before you add API keys.

Example

Save as minimal_agent.py:

from arcflow import Agent, Workflow

summarizer = Agent(
 name="summarizer",
 role="Summarizer",
 instructions="Summarize the user topic in two short paragraphs.",
)

workflow = Workflow("minimal-agent-demo")
workflow.step(summarizer)

result = workflow.run("Benefits of local-first software")
print(result.output)
print(f"status={result.status} steps={result.step_count}")

Run:

python minimal_agent.py

You defined one agent, registered it as the only step, and passed a run input string. The runtime executed that single step and returned its output on result.output.

Verify

If construction fails with WorkflowConfigurationError, one of the three required strings is blank or whitespace only.

Next

02 Instructions that work covers how to write instructions that produce useful behavior when you switch from stub to a real provider.