API Reference

Complete API reference for the isA Agent SDK.

Agent Class

The primary interface for creating and running agents.


from isa_agent_sdk import Agent
 
# L1: Zero config
agent = Agent("assistant")
 
# L2: Common params
agent = Agent("coder", tools=["Read", "Write"], model="claude-sonnet")
 
# L3: Full options
agent = Agent("expert", options=ISAAgentOptions(
    mode=ExecutionMode.COLLABORATIVE,
    guardrail_mode=GuardrailMode.STRICT,
    max_iterations=50,
))

Methods

Method	Returns	Description
`agent.run(message)`	`AgentRunResult`	Send a message and get a complete response
`agent.stream(message)`	`AsyncIterable[AgentMessage]`	Stream events as they arrive
`Agent.auto_team(agents)`	`Agent`	Create a team that auto-selects the best agent

ISAAgentOptions

Full configuration for agent behavior.


from isa_agent_sdk import ISAAgentOptions, ExecutionMode, ToolDiscovery

Key Fields

Field	Type	Default	Description
`model`	`str`	`None`	Model name for reasoning
`system_prompt`	`str`	`None`	System prompt override
`mode`	`ExecutionMode`	`REACTIVE`	Execution mode
`tool_discovery`	`ToolDiscovery`	`HYBRID`	Tool discovery strategy
`permission_mode`	`PermissionMode`	`DEFAULT`	Permission enforcement
`guardrail_mode`	`GuardrailMode`	`MODERATE`	Safety guardrail strictness
`tools`	`list[str]`	`[]`	Tools to make available
`skills`	`list[str]`	`[]`	Skills to enable
`max_iterations`	`int`	`25`	Max agent loop iterations
`temperature`	`float`	`None`	Model temperature
`max_tokens`	`int`	`None`	Max response tokens

Enums

ExecutionMode: REACTIVE (default), COLLABORATIVE, PROACTIVE

ToolDiscovery: EXPLICIT, SEMANTIC, HYBRID (default)

PermissionMode: DEFAULT, ACCEPT_EDITS, BYPASS_PERMISSIONS

GuardrailMode: PERMISSIVE, MODERATE (default), STRICT

AgentMessage

Events emitted during agent execution.


from isa_agent_sdk import AgentMessage, EventType

EventType Values

Event	Description
`session.created`	New session started
`session.resumed`	Existing session resumed
`content.start`	Response generation started
`content.delta`	Incremental content chunk
`content.complete`	Full response complete
`tool.start`	Tool execution started
`tool.result`	Tool returned a result
`tool.error`	Tool execution failed

Tool Definition

Define custom tools for agent use.


from isa_agent_sdk import tool
 
@tool()
async def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: sunny"

Parameters are inferred from type hints. The tool is automatically registered with the MCP server.

Multi-Agent Orchestration

Swarm

Dynamic handoff between agents.


from isa_agent_sdk import SwarmOrchestrator
 
swarm = SwarmOrchestrator(agents=[researcher, writer])
result = await swarm.run("Research and write about AI agents")

Fan Out

Parallel execution across agents.


from isa_agent_sdk import fan_out
 
results = await fan_out([analyst, researcher], "Analyze this data")

Refinement

Iterative improvement loop.


from isa_agent_sdk import refine
 
result = await refine(editor, "Write a haiku", max_iterations=3)

Detached AgentRun API

For work that should continue after the request returns, use the current detached run API. It queues the run and exposes status and event streams.


from isa_agent_sdk import submit_agent_run, stream_agent_run
 
handle = await submit_agent_run(
    prompt="分析这个代码库",
    options=ISAAgentOptions(model="gpt-4o-mini"),
)
 
async for event in stream_agent_run(handle.run_id):
    print(event.type, event.status)

ISAAgentClient

HTTP + SSE client for connecting to deployed agents.


from isa_agent_sdk import ISAAgentClient
 
client = ISAAgentClient(base_url="http://localhost:8080")
 
# Non-streaming
result = await client.chat.create("Hello", user_id="user-1")
 
# Streaming
async for event in client.chat.stream("Hello", user_id="user-1"):
    print(event.type, event.data)

TypeScript SDK


import { Agent, defineTool, swarm } from "@isa-agent/sdk";
 
const agent = new Agent("assistant", { model: "claude-sonnet" });
const result = await agent.run("Hello!");

See the TypeScript SDK source for full API.