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 -
.isadirectory 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
isa_agent_sdk-0.5.28.tar.gz
(1.6 MB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file isa_agent_sdk-0.5.28.tar.gz.
File metadata
- Download URL: isa_agent_sdk-0.5.28.tar.gz
- Upload date:
- Size: 1.6 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a23903f1e8cbc74f36816c1b0f17df448084ffdc5b85d0262c8504a4f426eaae
|
|
| MD5 |
2b4e02c7da612a131cb984622afd9578
|
|
| BLAKE2b-256 |
1db3f361da5199f9341be3f1f6a081fab9b37e3f573160db6a0d6f2016eb7a6b
|
File details
Details for the file isa_agent_sdk-0.5.28-py3-none-any.whl.
File metadata
- Download URL: isa_agent_sdk-0.5.28-py3-none-any.whl
- Upload date:
- Size: 1.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b5a88f75e8c88682745e5d673bf66d6773dbb6fcfaa9d7d63bb25906cf64de04
|
|
| MD5 |
b8d4b89e7850535e2fe9afaa5fa69cca
|
|
| BLAKE2b-256 |
ed21ff162d1d6cae2b8c86f7fe95771e663323db244438d878591e9494c9f73c
|
