agentforge-markets 1.0.0
Official Python SDK for AgentForge AI Agent Tool Marketplace
Requires Python: >=3.8
Keywords: agent, ai, marketplace, mcp, sdk, tools

# agentforge-sdk

Official Python SDK for the [AgentForge](https://agentforge.markets) AI Agent Tool Marketplace.

Discover, execute, and manage AI tools from a unified API. Single dependency: `httpx`.

## Install

```bash
pip install agentforge-sdk
```

## Quick Start

```python
from agentforge import AgentForge

agent = AgentForge(api_key="agf_agent_...")
tools = agent.discover(intent="translate text to French")
result = agent.execute(tools["tools"][0]["id"], {"text": "Hello", "target": "fr"})
print(result["data"])
```

## Features

- **Tool Discovery** -- search by intent, category, protocol, tags, or price
- **Schema Retrieval** -- get function-calling compatible schemas for any tool
- **Execution** -- call any tool with typed parameters and get structured results
- **Batch Execution** -- run up to 10 tool calls in a single request
- **Retry with Backoff** -- exponential backoff with jitter (configurable)
- **Circuit Breaker** -- check tool health before calling unreliable endpoints
- **Billing** -- check balance, deposit funds, view call history
- **Minimal Dependencies** -- only `httpx` required

## Configuration

```python
agent = AgentForge(
    api_key="agf_agent_...",
    base_url="https://api.agentforge.markets",  # default
    timeout=30.0,                             # default: 30s
    max_retries=3,                            # default: 3, set 0 to disable
)
```

Use as a context manager for automatic cleanup:

```python
with AgentForge(api_key="agf_agent_...") as agent:
    result = agent.execute("tool-uuid", {"text": "Hello"})
```

## API Reference

### Discovery

```python
# Discover tools by intent (natural language)
result = agent.discover(intent="summarize a webpage")

# Filter by category and price
cheap = agent.discover(category="nlp", maxPrice=0.01)

# List all tools with pagination
page = agent.list_tools(limit=20, offset=0)

# Get function-calling schema
schema = agent.get_tool_schema("tool-uuid")
```

### Execution

```python
# Execute a single tool
result = agent.execute("tool-uuid", {"text": "Hello world"})

# Batch execution (up to 10 calls)
batch = agent.execute_batch([
    {"toolId": "tool-1", "parameters": {"query": "AI news"}},
    {"toolId": "tool-2", "parameters": {"url": "https://example.com"}},
])
```

### Billing

```python
balance = agent.get_balance()
agent.deposit(10.00)
history = agent.get_history(limit=20)
```

### Health Check

```python
health = agent.health_check("tool-uuid")
# health["status"]: "CLOSED" (healthy) | "OPEN" (failing) | "HALF_OPEN" (testing)
```

## Error Handling

```python
from agentforge import AgentForge, AgentForgeError

agent = AgentForge(api_key="agf_agent_...")

try:
    agent.execute("tool-uuid", {"text": "test"})
except AgentForgeError as e:
    print(e.code)         # "INSUFFICIENT_FUNDS", "TIMEOUT", etc.
    print(e.status_code)  # HTTP status code
    print(e.retryable)    # whether the SDK would auto-retry
```

### Error Codes

| Code                  | HTTP | Description                           |
|-----------------------|------|---------------------------------------|
| `UNAUTHORIZED`        | 401  | Invalid or missing API key            |
| `FORBIDDEN`           | 403  | Insufficient permissions              |
| `NOT_FOUND`           | 404  | Tool or resource not found            |
| `INSUFFICIENT_FUNDS`  | 402  | Agent balance too low                 |
| `VALIDATION_ERROR`    | 400  | Invalid request parameters            |
| `RATE_LIMITED`        | 429  | Too many requests                     |
| `TIMEOUT`             | --   | Request exceeded timeout              |
| `NETWORK_ERROR`       | --   | Connection failure                    |
| `SERVER_ERROR`        | 5xx  | AgentForge server error               |
| `CIRCUIT_OPEN`        | 503  | Tool endpoint failing (circuit open)  |

## Use with LLMs

The SDK works seamlessly with LLM function-calling workflows:

```python
import anthropic
from agentforge import AgentForge

client = anthropic.Anthropic()
forge = AgentForge(api_key="agf_agent_...")

# Discover tools and build function definitions
discovered = forge.discover(intent=user_message)
tools = []
for t in discovered["tools"][:5]:
    schema = forge.get_tool_schema(t["id"])
    tools.append({
        "name": schema["function"]["name"],
        "description": schema["function"]["description"],
        "input_schema": schema["function"]["parameters"],
    })

# Let Claude decide which tool to use
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": user_message}],
)
```

## Full Documentation

Visit [agentforge.markets/docs](https://agentforge.markets/docs) for the complete API reference, guides, and examples.

## License

MIT