Python SDK
Use Facio as a Python library when you need to embed one direct agent run.
The Docker quickstart is the normal way to operate Facio with Placet, channels, management, MCP, cron, and durable service state. The Python SDK is narrower: it embeds the Facio agent loop in your own Python process and runs one direct request at a time.
Use it for tests, internal scripts, and controlled application integration where you already manage configuration and workspace paths.
Basic run
import asyncio
from facio import Facio
async def main() -> None:
bot = Facio.from_config(
config_path="./config.json",
workspace="./workspace",
)
result = await bot.run(
"Summarize the current workspace.",
session_key="sdk:summary",
)
print(result.content)
asyncio.run(main())API shape
| Object or method | Meaning |
|---|---|
Facio.from_config(config_path, workspace=...) | Load config, resolve environment variables, create the provider, and build an agent loop. |
await bot.run(message, session_key=..., hooks=...) | Process one direct message through the agent loop. Different session keys keep history separate. |
RunResult.content | Assistant text for the completed run. |
RunResult.tools_used | Reserved for tool usage summaries. |
RunResult.messages | Reserved for returned message details. |
Configuration
The SDK uses the same config.json schema as the gateway and CLI. Pass config_path explicitly in embedded applications so the process does not depend on a user-level default config location.
Provider validation is the same as the CLI: hosted providers need usable credentials, local providers need a reachable apiBase, and OAuth-backed providers must already be logged in before the SDK run starts.
Hooks
run() accepts optional agent lifecycle hooks:
result = await bot.run(
"Prepare a review summary.",
session_key="sdk:review",
hooks=[my_hook],
)Use hooks for controlled instrumentation or policy integration inside the host process. Use the gateway and Placet management API when you need operator-visible approvals, channel routing, or long-running service controls.