usf-agents 1.1.0.post12

A lightweight multi-agent orchestration framework with better control, easy to use for complex to simple use cases. Developer friendly with more visibility and supports all models with OpenAI compatible API.

USF Agents — Simplify the Complex, Amplify the Intelligent for Enterprise

Orchestrate multiple agents with ease: register agents, integrate tools, define custom instructions, and leverage multiple models.
Enterprise-grade and production-ready, with full control, deep customization, strong defaults, clear boundaries, and developer-focused APIs.

---

USF Agents

This is the official documentation for the USF Agents Python SDK.

Important: Responses are now OpenAI-compatible by default

• Non-streaming methods return OpenAI chat.completion dicts: object="chat.completion"
• Streaming methods yield OpenAI chat.completion.chunk dicts: object="chat.completion.chunk"
• USF-only stages are indicated via vendor extension x_usf, e.g. {"stage":"plan"} or {"stage":"tool_result"}

📖 Docs: Quickstart | Installation | Configuration | Troubleshooting / FAQ

---

Installation & Requirements

Requirements

• Python 3.9+
• USF API key (set as an environment variable)

Install the SDK

pip install usf-agents

Other package managers:

# uv
uv add usf-agents

# poetry
poetry add usf-agents

# pdm
pdm add usf-agents

Set Your API Key

# macOS/Linux
export USF_API_KEY=YOUR_KEY

# Windows PowerShell
$env:USF_API_KEY="YOUR_KEY"

# Windows CMD
set USF_API_KEY=YOUR_KEY

(Optional) Virtual Environment

python -m venv .venv

# macOS/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Verify Installation

pip show usf-agents

Minimal import check:

python - <<'PY'
try:
    import usf_agents
    print("usf_agents import: OK")
except Exception as e:
    print("Import failed:", e)
PY

---

Quick Sanity Run

Requires your USF_API_KEY to be set.

Non-streaming (OpenAI chat.completion):

# sanity.py
import os
import asyncio
import nest_asyncio
from usf_agents import ManagerAgent

nest_asyncio.apply()

async def main():
    mgr = ManagerAgent(
        usf_config={
            "api_key": os.getenv("USF_API_KEY"),
            "model": "usf-mini",
        }
    )
    completion = await mgr.run("Say 'hello world'", {"mode": "auto"})
    # completion is OpenAI-compatible: object="chat.completion"
    choice = (completion.get("choices") or [{}])[0] or {}
    message = choice.get("message") or {}
    if message.get("tool_calls"):
        print("Tool Calls (finish_reason=tool_calls):", message.get("tool_calls"))
    else:
        print("Final:", (message.get("content") or ""))

if __name__ == "__main__":
    asyncio.run(main())

Streaming (OpenAI chat.completion.chunk):

# stream_sanity.py
import os
import asyncio
import nest_asyncio
from usf_agents import ManagerAgent

nest_asyncio.apply()

async def main():
    mgr = ManagerAgent(
        usf_config={
            "api_key": os.getenv("USF_API_KEY"),
            "model": "usf-mini",
        }
    )
    async for chunk in mgr.stream(
        "Briefly introduce yourself.",
        {"mode": "auto", "streaming": {"plan_chunk_size": 80}}
    ):
        # chunk is OpenAI-compatible: object="chat.completion.chunk"
        delta = ((chunk.get("choices") or [{}])[0] or {}).get("delta") or {}
        x_usf = chunk.get("x_usf") or {}
        stage = x_usf.get("stage")
        if "tool_calls" in delta:
            print("stream tool_calls:", delta["tool_calls"])
        elif "content" in delta and delta["content"]:
            if stage == "plan":
                print("stream plan delta:", delta["content"])
            else:
                print("stream final delta:", delta["content"])
        elif stage == "tool_result":
            print("stream tool_result:", x_usf)
        finish = ((chunk.get("choices") or [{}])[0] or {}).get("finish_reason")
        if finish:
            print("stream finished with reason:", finish)

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python sanity.py
python stream_sanity.py

---

Migration Note

This release adopts OpenAI-compatible response formats by default:

• ManagerAgent.run(...) returns an OpenAI chat.completion dict.
• ManagerAgent.stream(...) yields OpenAI chat.completion.chunk dicts.
• Ephemeral helpers (run_ephemeral, run_ephemeral_final, run_many_parallel) now produce OpenAI shapes as well.

Breaking changes:

• Legacy shapes like {'status': 'final' | 'tool_calls', 'content': ..., 'tool_calls': [...]} are removed.
• Update integrations to read choices[0].message.* for non-stream, and choices[0].delta.* for streaming.

---

Documentation

Getting Started

• Quickstart
• Installation
• Configuration
• Troubleshooting / FAQ

Tools

• Overview
• Docstrings
• Decorator
• Explicit Schema
• Type Mapping
• Registry & Batching

Multi-Agent

• Overview
• Execution Modes
• Context Modes
• Manager-driven Delegation
• Skip Planning (No Tools)
• Custom Instruction

Jupyter Notebook Guides

• Email Drafting Assistant
• Customer Support Triage
• Planner-Worker Delegation
• Strict JSON Output
• Currency Converter

FastAPI Apps

• Email Drafting Assistant
• Customer Support Triage
• Planner-Worker Delegation
• Strict JSON Output
• Currency Converter

---

License

See LICENSE.