ff-sdk-py

Python client SDK for FireFoundry Agent Bundle services.

Use this SDK to invoke entity methods, run bots, and stream responses from FireFoundry Agent Bundle microservices deployed in your environment.

Installation

pip install ff-sdk

Quick Start

from ff_sdk import RemoteAgentBundleClient

client = RemoteAgentBundleClient(
    base_url="https://your-agent-bundle.example.com",
    api_key="your-api-key",
)

# Invoke an entity method
result = client.invoke_entity_method("entity-uuid", "generate_report", {"format": "pdf"})

# Run a bot
output = client.run_bot("SummaryBot", {"input": "Summarize this document"})

# Stream bot responses
iterator = client.start_bot("AnalysisBot", {"input": "Analyze trends"})
for update in iterator:
    print(update)

Async Usage

from ff_sdk import AsyncRemoteAgentBundleClient

async def main():
    async with AsyncRemoteAgentBundleClient(
        base_url="https://your-agent-bundle.example.com",
        api_key="your-api-key",
    ) as client:
        result = await client.invoke_entity_method("entity-uuid", "my_method", "arg1")

        # Stream with async for
        iterator = await client.start_iterator("entity-uuid", "process")
        async for item in iterator:
            print(item)
        await iterator.cleanup()

Entity Proxy

from ff_sdk import RemoteAgentBundleClient, EntityProxy

client = RemoteAgentBundleClient(base_url="...", api_key="...")
proxy = EntityProxy(entity_id="entity-uuid", client=client)

# Property access dispatches to invoke_entity_method
result = proxy.generate_report({"format": "pdf"})

Binary Data

# Upload a file
with open("document.pdf", "rb") as f:
    pdf_bytes = f.read()

result = client.invoke_entity_method_with_blobs(
    entity_id="entity-uuid",
    method_name="process_document",
    args=[{"$blob": 0}, {"title": "My Doc"}],
    files=[pdf_bytes],
)

# Download binary output efficiently (no base64 overhead)
pdf_output: bytes = client.invoke_entity_method_binary(
    "entity-uuid", "generate_large_pdf", {"pages": 1000}
)

Unified invoke Dispatcher

# JSON result (default)
result = client.invoke("entity-uuid", "process", args=[{"key": "val"}])

# Binary result
pdf = client.invoke("entity-uuid", "generate_pdf", response_type="binary")

# Streaming iterator
iterator = client.invoke("entity-uuid", "start", response_type="iterator")

Configuration

Parameter	Type	Default	Description
base_url	str	required	Base URL of the Agent Bundle service
api_key	str | None	None	API key for authentication
timeout	float	200.0	Request timeout in seconds
is_external	bool	False	Use gateway auth mode (plain key, no Bearer prefix)

License

MIT