Python SDK Reference

This page documents the public API of syntic-agent-sdk, the Python distribution of the Syntic Agent SDK. All exports connect to Amara on the Syntic model through api.syntic.ai. Install with pip install syntic-agent-sdk and import from the package root.

from syntic_agent_sdk import query, tool, create_sdk_mcp_server

The Python SDK is fully asynchronous and is designed to run inside an asyncio event loop. Its shapes mirror the TypeScript SDK so concepts transfer directly, with Python idioms substituted for TypeScript ones.

query()

query() is the entry point for running an agent. It is an async generator: iterate it with async for to receive messages as Amara reasons, calls tools, and returns a result.

async def query(
    *,
    prompt: str | AsyncIterable[dict],
    options: dict | None = None,
) -> AsyncIterator[Message]:
    ...

Pass a string prompt for a one-shot request, or an async iterable of user-message dicts for a live streaming session. The generator completes after it yields a result message.

import asyncio
from syntic_agent_sdk import query
 
async def main():
    async for message in query(
        prompt="Refactor utils.py to remove duplication.",
        options={"cwd": ".", "permission_mode": "acceptEdits"},
    ):
        if message.type == "assistant":
            print(message.text, end="", flush=True)
        if message.type == "result":
            print("\nDone:", message.result)
 
asyncio.run(main())

options

The options mapping configures the agent. Keys use snake_case; all are optional.

Key	Type	Description
`cwd`	`str`	Working directory for the agent.
`model`	`str`	Syntic model identifier for Amara.
`system_prompt`	`str \| dict`	Replace or extend the default system prompt.
`permission_mode`	`str`	`"default"`, `"acceptEdits"`, `"plan"`, or `"bypassPermissions"`.
`allowed_tools`	`list[str]`	Tools Amara may use.
`disallowed_tools`	`list[str]`	Tools to exclude.
`mcp_servers`	`dict`	MCP servers to connect, including in-process ones.
`can_use_tool`	`Callable`	Async approval callback per tool call.
`hooks`	`dict`	Lifecycle hook callbacks.
`max_turns`	`int`	Cap on agent loop iterations.
`resume`	`str`	Session id to resume a persisted conversation.

Messages

Each yielded object has a .type attribute you branch on.

`type`	Meaning
`system`	Session initialization and metadata.
`assistant`	Text or tool calls from Amara.
`user`	User or tool-result content.
`result`	Terminal message with `result`, `usage`, and `total_cost_usd`.

Read usage and total_cost_usd from the result message for cost tracking.

tool and permission callbacks

Define in-process tools with the @tool decorator and expose them with create_sdk_mcp_server(). The decorator declares a name, description, and input schema.

from syntic_agent_sdk import tool, create_sdk_mcp_server
 
@tool("get_weather", "Return the current weather for a city.", {"city": str})
async def get_weather(args):
    return {"content": [{"type": "text", "text": f"Sunny in {args['city']}."}]}
 
server = create_sdk_mcp_server(name="weather", tools=[get_weather])

Pass the server via options["mcp_servers"]. The can_use_tool callback receives the tool name and input and returns an approval decision — allow, deny, or a modified input. See Custom tools and Permissions.

TypeScript SDK Migration Guide