Metadata-Version: 2.4
Name: agentsdk-py
Version: 0.1.0
Summary: A lightweight Python SDK for building AI agents with tools, memory, and multi-agent pipelines — powered by Groq
License-Expression: MIT
Project-URL: Homepage, https://github.com/vishwa0198/agentsdk
Project-URL: Documentation, https://vishwa0198.github.io/agentsdk
Project-URL: Repository, https://github.com/vishwa0198/agentsdk
Project-URL: Changelog, https://github.com/vishwa0198/agentsdk/blob/main/CHANGELOG.md
Keywords: ai,agents,llm,groq,sdk,multi-agent,react-agent,tool-use
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: aiofiles>=23.0
Requires-Dist: groq>=0.9
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.24; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.24; extra == "otel"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: python-dotenv>=1.0; extra == "dev"

# agentsdk

A lightweight Python SDK for building AI agents with tool use, multi-agent graphs, persistence, and tracing.

## Install

```bash
pip install agentsdk          # core
pip install agentsdk[otel]    # + OpenTelemetry tracing
pip install agentsdk[dev]     # + pytest / dotenv
```

## Quickstart

```python
import asyncio, os
from agentsdk import Agent, AgentConfig, GroqProvider

agent = Agent(
    config=AgentConfig(
        name="MyAgent",
        system_prompt="You are a helpful assistant.",
    ),
    llm=GroqProvider(api_key=os.environ["GROQ_API_KEY"]),
)

async def main():
    result = await agent.run("What is the capital of France?")
    print(result.output)

asyncio.run(main())
```

## Tools

```python
from agentsdk import tool, ToolRegistry, Agent, AgentConfig, GroqProvider

@tool
async def add(a: int, b: int) -> str:
    """Add two integers."""
    return str(a + b)

registry = ToolRegistry()
registry.register(add)

agent = Agent(config=AgentConfig(name="Calc", system_prompt="Use tools."),
              llm=GroqProvider(...), registry=registry)
```

## Multi-agent Graph

```python
from agentsdk import AgentNode, Edge, AgentGraph, GraphRunner

graph = AgentGraph()
graph.add_node(AgentNode("researcher", researcher_agent))
graph.add_node(AgentNode("writer", writer_agent))
graph.add_edge(Edge("researcher", "writer", data_map={"output": "input"}))
graph.set_entry("researcher"); graph.set_exit("writer")
result = await GraphRunner(graph).run({"input": "Explain black holes"})
```

## Persistence

```python
from agentsdk import FileCheckpointStore, SessionManager, Agent

store = FileCheckpointStore(base_dir=".agentsdk/checkpoints")
session_mgr = SessionManager(store=store, agent_name="MyAgent")
agent = Agent(config=..., llm=..., session_manager=session_mgr)

# History is saved and reloaded automatically across runs:
await agent.run("My favourite language is Python.", session_id="user-001")
await agent.run("What language did I mention?",     session_id="user-001")

# Fork a session to branch an agent run:
forked = await session_mgr.fork("user-001", "user-001-branch")
```

## Tracing (requires `agentsdk[otel]`)

```python
from agentsdk.observability import SDKTracer, TracedLLMProvider, TracedAgent, print_trace

tracer     = SDKTracer(service_name="myapp")
traced_llm = TracedLLMProvider(provider=GroqProvider(...), tracer=tracer)
agent      = TracedAgent(config=..., llm=traced_llm, tracer=tracer)

result, ctx = await agent.run("Summarise the last quarter earnings.")
print_trace(ctx)
# ╔══ Trace: MyAgent ══════════════════════
# ║  Session     : (none)
# ║  Trace ID    : 6744d6eca33853c5bba0...
# ║  Duration    : 3680ms
# ║  LLM calls   : 2
# ║  Tool calls  : 1
# ║  Tokens      : 1292 in / 36 out
# ╚═════════════════════════════════════════
```

## CLI

```bash
# Scaffold a new agent project
scaffold-agent new myproject

# Interactive REPL against any agent file
scaffold-agent run myproject/agents/main.py

# Inspect a saved checkpoint
scaffold-agent trace .agentsdk/checkpoints/MyAgent/user-001.json

# List all sessions for an agent
scaffold-agent list-sessions MyAgent
```
