1.0.0

agentforge-sdk

Official Python SDK for the AgentForge AI Agent Tool Marketplace.

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

Install

pip install agentforge-sdk

Quick Start

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

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:

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

API Reference

Discovery

# 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

# 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

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

Health Check

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

Error Handling

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

Use with LLMs

The SDK works seamlessly with LLM function-calling workflows:

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 for the complete API reference, guides, and examples.

License

MIT