API Reference

from a1 import Agent
from pydantic import BaseModel

class Input(BaseModel):
    query: str

class Output(BaseModel):
    result: str

agent = Agent(
    name="my_agent",
    description="Does something useful",
    input_schema=Input,
    output_schema=Output,
    tools=[tool1, tool2],
    skills=[skill1, skill2]
)

# Compile ahead-of-time
compiled = await agent.aot(cache=True, strategy=None)

# Execute just-in-time
result = await agent.jit(query="example")

from a1 import tool

@tool
async def my_tool(x: int, y: str) -> dict:
    """Does something useful."""
    return {"result": f"{y}: {x}"}

# Or create explicitly
from a1 import Tool
from pydantic import BaseModel

class ToolInput(BaseModel):
    x: int
    y: str

class ToolOutput(BaseModel):
    result: str

tool = Tool(
    name="my_tool",
    description="Does something useful",
    input_schema=ToolInput,
    output_schema=ToolOutput,
    execute=lambda x, y: {"result": f"{y}: {x}"},
    is_terminal=False
)

from a1 import LLM

llm = LLM(
    model="gpt-4.1",
    retry_strategy=None,
    output_schema=None
)

# Use in agent
agent = Agent(
    name="agent",
    description="Uses LLM",
    tools=[my_tool, LLM("gpt-4.1-mini")]
)

from a1 import ToolSet

toolset = ToolSet(
    name="math_tools",
    description="Mathematical operations",
    tools=[add, subtract, multiply]
)

# Access tools
all_tools = toolset.get_all_tools()
specific_tool = toolset.get_tool("add")

from a1 import Skill

skill = Skill(
    name="python_basics",
    description="Python programming fundamentals",
    content="def example(): ...",
    modules=["os", "sys"]
)

from a1 import SkillSet

skillset = SkillSet(
    name="web_dev",
    description="Web development skills",
    skills=[html_skill, css_skill, js_skill]
)

from a1 import Strategy

strategy = Strategy(
    max_iterations=3,        # Max retry attempts
    num_candidates=1,        # Parallel code candidates
    generate=None,           # Custom code generator
    verify=None,             # Custom verifiers
    cost=None,               # Custom cost function
    compact=None             # Custom compaction
)

from a1 import RetryStrategy

retry = RetryStrategy(
    max_iterations=3,    # Max retry attempts with exponential backoff
    num_candidates=1     # Number of parallel attempts
)

from a1 import get_context

ctx = get_context("main")
ctx.user("What is 2+2?")
ctx.assistant("The answer is 4")
ctx.tool("calculator", input={"a": 2, "b": 2}, output={"result": 4})

# Access messages
messages = ctx.messages

from a1 import rag

# Database RAG
db_tools = rag.database("duckdb://path/to/db.duckdb")

# Filesystem RAG
fs_tools = rag.filesystem("/path/to/files")

# Combined
agent = Agent(
    name="rag_agent",
    description="Uses RAG",
    tools=[*db_tools, *fs_tools, LLM("gpt-4.1")]
)

from a1 import Runtime, set_runtime

runtime = Runtime(cache_dir="./cache")
set_runtime(runtime)

# Execute tool
result = await runtime.execute(tool, **kwargs)

# AOT compilation
compiled = await runtime.aot(agent, cache=True)

# JIT execution
result = await runtime.jit(agent, **kwargs)

# Context management
ctx = runtime.get_full_context(labels=["main", "attempt"])

from a1 import IsLoop, IsFunction

# Require while loop pattern
runtime.verify = [IsLoop()]

# Require async function
runtime.verify = [IsFunction()]