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.29.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.29.tar.gz.
File metadata
- Download URL: isa_agent_sdk-0.5.29.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 |
02743e1b0ec938049a69d7db1752104cb1686c6676f68a4de38711a2015ffae5
|
|
| MD5 |
c9ce81795c7d9ead01e22a55fbe24b69
|
|
| BLAKE2b-256 |
3102c13b8fcaf41b4cf5cacf8cc960fc70275207773a35c084453089a15e6906
|
File details
Details for the file isa_agent_sdk-0.5.29-py3-none-any.whl.
File metadata
- Download URL: isa_agent_sdk-0.5.29-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 |
a9edafdeac42628cc4ca51aced89c11ed16c9720f6abe75133bb9f56df55b4aa
|
|
| MD5 |
53a25d913e1edcacee4516ec80d46489
|
|
| BLAKE2b-256 |
b4fb92de9f3f97b58be007c13392bef19660a0054913873d712cea30ef98bfab
|
