# 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](https://agents-docs.us.inc/docs/quickstart) | [Installation](https://agents-docs.us.inc/docs/start/installation) | [Configuration](https://agents-docs.us.inc/docs/start/configuration) | [Troubleshooting / FAQ](https://agents-docs.us.inc/docs/troubleshooting-faq)
---
## Installation & Requirements
### Requirements
- Python **3.9+**
- USF API key (set as an environment variable)
### Install the SDK
```bash
pip install usf-agents
````
Other package managers:
```bash
# uv
uv add usf-agents
# poetry
poetry add usf-agents
# pdm
pdm add usf-agents
```
### Set Your API Key
```bash
# 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
```bash
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
```
### Verify Installation
```bash
pip show usf-agents
```
Minimal import check:
```bash
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):
```python
# 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):
```python
# 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:
```bash
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](https://agents-docs.us.inc/docs/quickstart)
* [Installation](https://agents-docs.us.inc/docs/start/installation)
* [Configuration](https://agents-docs.us.inc/docs/start/configuration)
* [Troubleshooting / FAQ](https://agents-docs.us.inc/docs/troubleshooting-faq)
### Tools
* [Overview](https://agents-docs.us.inc/docs/tools/overview)
* [Docstrings](https://agents-docs.us.inc/docs/tools/docstrings)
* [Decorator](https://agents-docs.us.inc/docs/tools/decorator)
* [Explicit Schema](https://agents-docs.us.inc/docs/tools/explicit-schema)
* [Type Mapping](https://agents-docs.us.inc/docs/tools/type-mapping)
* [Registry & Batching](https://agents-docs.us.inc/docs/tools/registry-and-batch-tool-registration)
### Multi-Agent
* [Overview](https://agents-docs.us.inc/docs/multi-agent/overview)
* [Execution Modes](https://agents-docs.us.inc/docs/multi-agent/auto-execution-modes)
* [Context Modes](https://agents-docs.us.inc/docs/multi-agent/context-modes)
* [Manager-driven Delegation](https://agents-docs.us.inc/docs/multi-agent/manager-driven-delegation)
* [Skip Planning (No Tools)](https://agents-docs.us.inc/docs/multi-agent/skip-planning-no-tools)
* [Custom Instruction](https://agents-docs.us.inc/docs/multi-agent/custom-instruction)
### Jupyter Notebook Guides
* [Email Drafting Assistant](https://agents-docs.us.inc/docs/jupyter-notebooks/email-drafting-assistant)
* [Customer Support Triage](https://agents-docs.us.inc/docs/jupyter-notebooks/customer-support-triage)
* [Planner-Worker Delegation](https://agents-docs.us.inc/docs/jupyter-notebooks/planner-worker-delegation)
* [Strict JSON Output](https://agents-docs.us.inc/docs/jupyter-notebooks/strict-json-output)
* [Currency Converter](https://agents-docs.us.inc/docs/jupyter-notebooks/currency-converter)
### FastAPI Apps
* [Email Drafting Assistant](https://agents-docs.us.inc/docs/fastapi-apps/email-drafting-assistant/README)
* [Customer Support Triage](https://agents-docs.us.inc/docs/fastapi-apps/customer-support-triage/README)
* [Planner-Worker Delegation](https://agents-docs.us.inc/docs/fastapi-apps/planner-worker-delegation/README)
* [Strict JSON Output](https://agents-docs.us.inc/docs/fastapi-apps/strict-json-output/README)
* [Currency Converter](https://agents-docs.us.inc/docs/fastapi-apps/currency-converter/README)
---
## License
See [LICENSE](https://agents-docs.us.inc/license).
Raw data
{
"_id": null,
"home_page": null,
"name": "usf-agents",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "multi-agent, orchestration, framework, lightweight, agent, developer-friendly, visibility, control, complex-usecase, simple-usecase, all-models, openai-compatible, llm, ai-agent, tool-calling, streaming, usf, planning, UltraSafe, UltraSafe AI, usf-agents",
"author": "UltraSafe AI Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/60/21/46daf44001d7f6ed31ad5de8436abcb66c5ef2866b825c4991a1932dee9a/usf_agents-1.1.0.post12.tar.gz",
"platform": null,
"description": "# USF Agents \u2014 Simplify the Complex, Amplify the Intelligent for Enterprise\n\nOrchestrate multiple agents with ease: register agents, integrate tools, define custom instructions, and leverage multiple models. \nEnterprise-grade and production-ready, with full control, deep customization, strong defaults, clear boundaries, and developer-focused APIs.\n\n---\n\n# USF Agents\n\nThis is the official documentation for the **USF Agents Python SDK**.\n\nImportant: Responses are now OpenAI-compatible by default\n- Non-streaming methods return OpenAI chat.completion dicts: object=\"chat.completion\"\n- Streaming methods yield OpenAI chat.completion.chunk dicts: object=\"chat.completion.chunk\"\n- USF-only stages are indicated via vendor extension x_usf, e.g. {\"stage\":\"plan\"} or {\"stage\":\"tool_result\"}\n\n\ud83d\udcd6 **Docs:** [Quickstart](https://agents-docs.us.inc/docs/quickstart) | [Installation](https://agents-docs.us.inc/docs/start/installation) | [Configuration](https://agents-docs.us.inc/docs/start/configuration) | [Troubleshooting / FAQ](https://agents-docs.us.inc/docs/troubleshooting-faq)\n\n---\n\n## Installation & Requirements\n\n### Requirements\n- Python **3.9+**\n- USF API key (set as an environment variable)\n\n### Install the SDK\n\n```bash\npip install usf-agents\n````\n\nOther package managers:\n\n```bash\n# uv\nuv add usf-agents\n\n# poetry\npoetry add usf-agents\n\n# pdm\npdm add usf-agents\n```\n\n### Set Your API Key\n\n```bash\n# macOS/Linux\nexport USF_API_KEY=YOUR_KEY\n\n# Windows PowerShell\n$env:USF_API_KEY=\"YOUR_KEY\"\n\n# Windows CMD\nset USF_API_KEY=YOUR_KEY\n```\n\n### (Optional) Virtual Environment\n\n```bash\npython -m venv .venv\n\n# macOS/Linux\nsource .venv/bin/activate\n\n# Windows PowerShell\n.venv\\Scripts\\Activate.ps1\n```\n\n### Verify Installation\n\n```bash\npip show usf-agents\n```\n\nMinimal import check:\n\n```bash\npython - <<'PY'\ntry:\n import usf_agents\n print(\"usf_agents import: OK\")\nexcept Exception as e:\n print(\"Import failed:\", e)\nPY\n```\n\n---\n\n## Quick Sanity Run\n\nRequires your `USF_API_KEY` to be set.\n\nNon-streaming (OpenAI chat.completion):\n\n```python\n# sanity.py\nimport os\nimport asyncio\nimport nest_asyncio\nfrom usf_agents import ManagerAgent\n\nnest_asyncio.apply()\n\nasync def main():\n mgr = ManagerAgent(\n usf_config={\n \"api_key\": os.getenv(\"USF_API_KEY\"),\n \"model\": \"usf-mini\",\n }\n )\n completion = await mgr.run(\"Say 'hello world'\", {\"mode\": \"auto\"})\n # completion is OpenAI-compatible: object=\"chat.completion\"\n choice = (completion.get(\"choices\") or [{}])[0] or {}\n message = choice.get(\"message\") or {}\n if message.get(\"tool_calls\"):\n print(\"Tool Calls (finish_reason=tool_calls):\", message.get(\"tool_calls\"))\n else:\n print(\"Final:\", (message.get(\"content\") or \"\"))\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\nStreaming (OpenAI chat.completion.chunk):\n\n```python\n# stream_sanity.py\nimport os\nimport asyncio\nimport nest_asyncio\nfrom usf_agents import ManagerAgent\n\nnest_asyncio.apply()\n\nasync def main():\n mgr = ManagerAgent(\n usf_config={\n \"api_key\": os.getenv(\"USF_API_KEY\"),\n \"model\": \"usf-mini\",\n }\n )\n async for chunk in mgr.stream(\n \"Briefly introduce yourself.\",\n {\"mode\": \"auto\", \"streaming\": {\"plan_chunk_size\": 80}}\n ):\n # chunk is OpenAI-compatible: object=\"chat.completion.chunk\"\n delta = ((chunk.get(\"choices\") or [{}])[0] or {}).get(\"delta\") or {}\n x_usf = chunk.get(\"x_usf\") or {}\n stage = x_usf.get(\"stage\")\n if \"tool_calls\" in delta:\n print(\"stream tool_calls:\", delta[\"tool_calls\"])\n elif \"content\" in delta and delta[\"content\"]:\n if stage == \"plan\":\n print(\"stream plan delta:\", delta[\"content\"])\n else:\n print(\"stream final delta:\", delta[\"content\"])\n elif stage == \"tool_result\":\n print(\"stream tool_result:\", x_usf)\n finish = ((chunk.get(\"choices\") or [{}])[0] or {}).get(\"finish_reason\")\n if finish:\n print(\"stream finished with reason:\", finish)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\nRun it:\n\n```bash\npython sanity.py\npython stream_sanity.py\n```\n\n---\n\n## Migration Note\n\nThis release adopts OpenAI-compatible response formats by default:\n- ManagerAgent.run(...) returns an OpenAI chat.completion dict.\n- ManagerAgent.stream(...) yields OpenAI chat.completion.chunk dicts.\n- Ephemeral helpers (run_ephemeral, run_ephemeral_final, run_many_parallel) now produce OpenAI shapes as well.\n\nBreaking changes:\n- Legacy shapes like {'status': 'final' | 'tool_calls', 'content': ..., 'tool_calls': [...]} are removed.\n- Update integrations to read choices[0].message.* for non-stream, and choices[0].delta.* for streaming.\n\n---\n\n## Documentation\n\n### Getting Started\n\n* [Quickstart](https://agents-docs.us.inc/docs/quickstart)\n* [Installation](https://agents-docs.us.inc/docs/start/installation)\n* [Configuration](https://agents-docs.us.inc/docs/start/configuration)\n* [Troubleshooting / FAQ](https://agents-docs.us.inc/docs/troubleshooting-faq)\n\n### Tools\n\n* [Overview](https://agents-docs.us.inc/docs/tools/overview)\n* [Docstrings](https://agents-docs.us.inc/docs/tools/docstrings)\n* [Decorator](https://agents-docs.us.inc/docs/tools/decorator)\n* [Explicit Schema](https://agents-docs.us.inc/docs/tools/explicit-schema)\n* [Type Mapping](https://agents-docs.us.inc/docs/tools/type-mapping)\n* [Registry & Batching](https://agents-docs.us.inc/docs/tools/registry-and-batch-tool-registration)\n\n### Multi-Agent\n\n* [Overview](https://agents-docs.us.inc/docs/multi-agent/overview)\n* [Execution Modes](https://agents-docs.us.inc/docs/multi-agent/auto-execution-modes)\n* [Context Modes](https://agents-docs.us.inc/docs/multi-agent/context-modes)\n* [Manager-driven Delegation](https://agents-docs.us.inc/docs/multi-agent/manager-driven-delegation)\n* [Skip Planning (No Tools)](https://agents-docs.us.inc/docs/multi-agent/skip-planning-no-tools)\n* [Custom Instruction](https://agents-docs.us.inc/docs/multi-agent/custom-instruction)\n\n### Jupyter Notebook Guides\n\n* [Email Drafting Assistant](https://agents-docs.us.inc/docs/jupyter-notebooks/email-drafting-assistant)\n* [Customer Support Triage](https://agents-docs.us.inc/docs/jupyter-notebooks/customer-support-triage)\n* [Planner-Worker Delegation](https://agents-docs.us.inc/docs/jupyter-notebooks/planner-worker-delegation)\n* [Strict JSON Output](https://agents-docs.us.inc/docs/jupyter-notebooks/strict-json-output)\n* [Currency Converter](https://agents-docs.us.inc/docs/jupyter-notebooks/currency-converter)\n\n### FastAPI Apps\n\n* [Email Drafting Assistant](https://agents-docs.us.inc/docs/fastapi-apps/email-drafting-assistant/README)\n* [Customer Support Triage](https://agents-docs.us.inc/docs/fastapi-apps/customer-support-triage/README)\n* [Planner-Worker Delegation](https://agents-docs.us.inc/docs/fastapi-apps/planner-worker-delegation/README)\n* [Strict JSON Output](https://agents-docs.us.inc/docs/fastapi-apps/strict-json-output/README)\n* [Currency Converter](https://agents-docs.us.inc/docs/fastapi-apps/currency-converter/README)\n\n---\n\n## License\n\nSee [LICENSE](https://agents-docs.us.inc/license).\n",
"bugtrack_url": null,
"license": "USF Agents SDK License",
"summary": "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.",
"version": "1.1.0.post12",
"project_urls": {
"Homepage": "https://us.inc"
},
"split_keywords": [
"multi-agent",
" orchestration",
" framework",
" lightweight",
" agent",
" developer-friendly",
" visibility",
" control",
" complex-usecase",
" simple-usecase",
" all-models",
" openai-compatible",
" llm",
" ai-agent",
" tool-calling",
" streaming",
" usf",
" planning",
" ultrasafe",
" ultrasafe ai",
" usf-agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f3a2d7ebaf7b95d6b5e0a82d9d7d828d7590803e6123949bf9fa6d2810d1f3a",
"md5": "9884892cf47387cebc071cb5c1c87b32",
"sha256": "a523deb1154de6310542a5b4b73bc16305d36e6a20a5b83a594a1e321b47ca48"
},
"downloads": -1,
"filename": "usf_agents-1.1.0.post12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9884892cf47387cebc071cb5c1c87b32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 62971,
"upload_time": "2025-09-10T04:53:38",
"upload_time_iso_8601": "2025-09-10T04:53:38.900045Z",
"url": "https://files.pythonhosted.org/packages/4f/3a/2d7ebaf7b95d6b5e0a82d9d7d828d7590803e6123949bf9fa6d2810d1f3a/usf_agents-1.1.0.post12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "602146daf44001d7f6ed31ad5de8436abcb66c5ef2866b825c4991a1932dee9a",
"md5": "0b89d02ca9e3a4f0826f69044f6638aa",
"sha256": "0f567e1823e89b84b714828477c9f19399e348557ee8ba5ecc49417edbf787b4"
},
"downloads": -1,
"filename": "usf_agents-1.1.0.post12.tar.gz",
"has_sig": false,
"md5_digest": "0b89d02ca9e3a4f0826f69044f6638aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 70044,
"upload_time": "2025-09-10T04:53:40",
"upload_time_iso_8601": "2025-09-10T04:53:40.553462Z",
"url": "https://files.pythonhosted.org/packages/60/21/46daf44001d7f6ed31ad5de8436abcb66c5ef2866b825c4991a1932dee9a/usf_agents-1.1.0.post12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 04:53:40",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "usf-agents"
}
JSON