SDK — arcana.run()

The simplest way to use Arcana. One async call, one result.

For multi-turn sessions, pipelines, or batch execution, use Runtime.

arcana.run

run async

run(goal: str, *, images: list[str] | None = None, tools: list[Callable] | None = None, provider: str = 'deepseek', model: str | None = None, api_key: str | None = None, max_turns: int = 20, max_cost_usd: float = 1.0, auto_route: bool = True, engine: str = 'conversation', stream: bool = False, response_format: type[BaseModel] | None = None, input_handler: Callable | None = None, system: str | None = None, context: dict[str, Any] | str | None = None, on_parse_error: Callable | None = None, skill_paths: list[str] | None = None, skills: list[str] | None = None) -> RunResult

Run an agent to accomplish a goal.

This is the simplest way to use Arcana. It handles provider setup, tool registration, intent routing, and execution automatically.

Quick run -- creates a temporary Runtime. For scripts and demos.

Parameters:

Name	Type	Description	Default
goal	str	What you want the agent to accomplish	required
images	list[str] | None	Optional list of image inputs. Each can be a URL, local file path, or data: URI / raw base64 string.	None
tools	list[Callable] | None	Optional list of @arcana.tool decorated functions	None
provider	str	LLM provider name (default: "deepseek")	'deepseek'
model	str | None	Model ID (auto-selected if None)	None
api_key	str | None	API key for the provider. If None, reads from environment variable.	None
max_turns	int	Maximum execution turns (default: 20)	20
max_cost_usd	float	Maximum cost in USD (default: 1.0)	1.0
auto_route	bool	Enable intent routing (default: True)	True
engine	str	Execution engine - "conversation" (V2, default) or "adaptive" (V1)	'conversation'
stream	bool	Enable streaming output (reserved for future use)	False
response_format	type[BaseModel] | None	Pydantic BaseModel class for structured output. When provided, the LLM is instructed to return JSON matching the model's schema, and result.output will be a validated instance of the model rather than a plain string. Tools and structured output can be used together — the agent uses tools during reasoning and returns structured output on the final turn.	None
input_handler	Callable | None	Optional callback for the ask_user built-in tool. Can be sync or async. When None, the LLM receives a fallback message and proceeds with best judgment.	None
system	str | None	System prompt defining the agent's role/persona for this run. When None, the engine's default is used.	None
context	dict[str, Any] | str | None	Additional context for the agent. A dict is serialized as JSON; a string is used as-is. Injected as a <context> block so the agent can reference prior outputs or external data.	None
skill_paths	list[str] | None	Optional SKILL.md paths/directories to load for this run. Empty by default; no skills are scanned or injected unless set.	None
skills	list[str] | None	Optional skill names to force into this run's working set.	None
on_parse_error	Callable | None	Optional callback invoked when the LLM returns text that cannot be parsed into the response_format model. Receives (raw_string, error) where error is a json.JSONDecodeError or pydantic.ValidationError. Return a fixed BaseModel instance to recover, or None to preserve the failure. Supports async. Does NOT fire for provider-level rejections (e.g. the provider does not support json_schema mode) -- those surface as ProviderError and are handled by provider capability detection / auto-downgrade.	None

Returns:

Type	Description
RunResult	RunResult with output and execution metadata

Examples:

Simplest usage

result = await arcana.run("What is 2+2?", api_key="sk-xxx")

With an image

result = await arcana.run( "Describe this image", images=["https://example.com/photo.jpg"], provider="openai", api_key="sk-proj-xxx", )

With tools

@arcana.tool(when_to_use="For math") def calc(expression: str) -> str: return str(eval(expression))

result = await arcana.run("15*37+89?", tools=[calc], api_key="sk-xxx")

With OpenAI

result = await arcana.run("Hello", provider="openai", api_key="sk-proj-xxx")

RunResult

The dataclass returned by arcana.run() and Runtime.run().

RunResult

Bases: BaseModel

Result of an arcana.run() call.