isA Agent SDK

A complete AI Agent SDK for building intelligent agents with advanced features. Compatible with Claude Agent SDK patterns, with additional capabilities.

Features

Claude Agent SDK Compatible - Familiar API patterns
Streaming Messages - Real-time response streaming
Built-in Tools - Read, Write, Edit, Bash, WebSearch, etc.
MCP Integration - Model Context Protocol with offline fallback
Human-in-the-Loop - Durable execution with checkpoints
Skills System - Local-first skill loading with MCP fallback
Project Config - .isa directory for project-specific settings
Event Triggers - Proactive agent activation
Multiple Execution Modes - Reactive, Collaborative, Proactive
A2A Ready - Agent Card + JSON-RPC client/server adapters
Multi-Agent Swarm - Dynamic agent handoffs with [HANDOFF:] directives
DAG Task Execution - Dependency-ordered workflows with parallel wavefronts
Production Resilience - Circuit breakers, bulkhead isolation, error classification, recovery playbooks
Observability - OpenTelemetry tracing, structured error logging, Prometheus metrics
Intent-Driven Routing - SenseNode classifies intent for automatic model tier selection
Graceful Degradation - Nodes skip optional operations when services are degraded
3,500+ Tests - Comprehensive coverage including chaos tests

Multi-Agent Patterns

Batch Swarm - Auto-decompose high-cardinality work, execute parallel DAG wavefronts, and synthesize the result.
Multi-Agent Orchestration - Fixed teams, dynamic spawning, and tier selection.
Swarm Orchestration - Handoff-driven agent collaboration.

Installation

pip install isa-agent-sdk

# With FastAPI server support
pip install isa-agent-sdk[server]

# With OpenTelemetry tracing
pip install isa-agent-sdk[observability]

Project Setup

Initialize a .isa directory for project-specific configuration:

mkdir -p .isa/skills

my-project/
├── .isa/
│   ├── config.json          # Project configuration
│   ├── settings.local.json  # MCP servers, permissions
│   └── skills/              # Local skills (loaded first)
│       └── my-skill/
│           └── SKILL.md
└── ...

Skills in .isa/skills/ are loaded before MCP, allowing project-specific overrides.

Quick Start

Basic Query

from isa_agent_sdk import query, ISAAgentOptions

# Simple usage
async for msg in query("Hello, world!"):
    print(msg.content)

# With options
async for msg in query(
    "Fix the bug in auth.py",
    options=ISAAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"],
        execution_mode="collaborative"
    )
):
    if msg.is_text:
        print(msg.content, end="")
    elif msg.is_tool_use:
        print(f"[Tool: {msg.tool_name}]")

Human-in-the-Loop

from isa_agent_sdk import request_tool_permission, checkpoint

# Request permission before dangerous operations
authorized = await request_tool_permission(
    "delete_file",
    {"path": "important_data.txt"}
)
if authorized:
    # proceed with deletion
    pass

# Create checkpoints for durable execution
await checkpoint("about_to_deploy", {
    "version": "1.0.0",
    "environment": "production"
})

HTTP Client (for deployed apps)

from isa_agent_sdk import ISAAgent

client = ISAAgent(base_url="http://localhost:8000")

# Non-streaming
response = client.chat.create(
    message="Explain quantum computing",
    user_id="user123"
)
print(response.content)

# Streaming
for event in client.chat.stream(
    message="Write a Python function",
    user_id="user123"
):
    if event.is_content:
        print(event.content, end="")

Building a FastAPI Agent Service

from fastapi import FastAPI
from isa_agent_sdk import query, ISAAgentOptions

app = FastAPI()

@app.post("/query")
async def agent_query(prompt: str):
    responses = []
    async for msg in query(prompt):
        if msg.is_text:
            responses.append(msg.content)
    return {"response": "".join(responses)}

A2A (Agent-to-Agent) Integration

from fastapi import FastAPI
from isa_agent_sdk import (
    A2AAgentCard,
    A2AClient,
    A2AServerAdapter,
    register_a2a_fastapi_routes,
    build_auth_service_token_validator,
)

# Build agent card
card = A2AAgentCard(
    name="isA Agent",
    url="https://agent.example.com/a2a",
    token_url="https://auth.example.com/oauth/token",
).to_dict()

# Client call to remote A2A agent
client = A2AClient("https://remote-agent.example.com")
response = await client.send_message("https://remote-agent.example.com/a2a", "Hello from isA")

# Server adapter maps A2A JSON-RPC -> isa_agent_sdk ask/query
adapter = A2AServerAdapter()
rpc_result = await adapter.handle_rpc({
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {"message": {"parts": [{"text": "Summarize this repo"}]}}
})

# Mount A2A endpoints in FastAPI
app = FastAPI()
register_a2a_fastapi_routes(
    app,
    adapter=adapter,
    agent_card=card,
    rpc_path="/a2a",
    auth_validator=build_auth_service_token_validator(
        "http://localhost:8201",
        required_scopes=["a2a.invoke"],
    ),
)

Execution Modes

Reactive - Responds to explicit requests
Collaborative - Checkpoints for human approval
Proactive - Anticipates needs, suggests actions

Documentation

License

MIT

Metadata

Release files for isa-agent-sdk 0.5.84

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for isa-agent-sdk 0.5.84
File	Size	Uploaded
isa_agent_sdk-0.5.84.tar.gz	1.9 MB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for isa-agent-sdk 0.5.84
File	Interpreter	ABI	Platform	Reset
isa_agent_sdk-0.5.84-py3-none-any.whl 2.2 MB Sep 29, 2026	Python 3	none	any	Details

Total release size: 4.1 MB

Release files / isa_agent_sdk-0.5.84.tar.gz

Download URL	isa_agent_sdk-0.5.84.tar.gz
Size	1.9 MB
Tags	Source
SHA-256 checksum How to use checksums	`523c34975a392e50f69ceddbf4e0e97bff9be1f7c65eadd052bb2191ab0ef624`
BLAKE2b-256 checksum How to use checksums	`c28348b1f4915e0df29a8786165f14a670619dce4ba23897ba3c5aa8d535b66c`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.2`

Release files / isa_agent_sdk-0.5.84-py3-none-any.whl

Download URL	isa_agent_sdk-0.5.84-py3-none-any.whl
Size	2.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`78b2091254a07078548d7b1ad1d326bbe4392928ecf4e62f48cafe4347b98741`
BLAKE2b-256 checksum How to use checksums	`e89ec9bd89c7a7256db54478a7e40d24b5c9b4210d365eb4aa2c0b9b67815d5e`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.2`