Agents

The class attributes an agent subclass may set, and the fields of the result one run returns. Generated from the Agent and ACPAgent classes and from AgentResult. How to use them is in Dispatching agents.

Agent

• system_prompt: str | None = None
• output_model: type[BaseModel] | None = None
• ask_policy: Literal['off', 'http'] = 'off'

ACPAgent

Adds to Agent, and inherits the three above.

• command: list[str] = ['npx', 'pi-acp']
• model: str | None = None
• thinking: str | None = None
• permission_policy: Literal['ask', 'auto_allow', 'auto_deny'] = 'ask'
• permission_timeout: float | None = None
• permission_timeout_action: Literal['deny', 'allow'] = 'deny'
• elicitation_policy: Literal['ask', 'decline'] = 'ask'
• max_repair_turns: int = 2
• env_allowlist: list[str] | None = None
• tooling: Literal['auto', 'mcp', 'native', 'http', 'none'] = 'auto'
• client_class: type[ACPClient] = ACPClient
• stats_provider: SessionStatsProvider | None = None

AgentSession

What open() yields; run() is open() plus one prompt().

• session_id: str
• await prompt(prompt: str = '') -> AgentResult
• One assignment on the held session; the result is the prompt's.

AgentResult

• status: Literal['complete', 'failed'] = 'complete'
• output: Any = None
• text: str = ''
• session_id: str | None = None
• stop_reason: str | None = None
• error: str | None = None
• stats: dict[str, Any] = dict()
• ok: property. Whether the run completed. status="failed" is not an error.