Metadata-Version: 2.4
Name: agent-zero
Version: 0.1.1
Summary: AI outbound voice agent framework
Author-email: Max Ilin <maksym@spacestep.ca>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp==3.11.16
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio==4.8.0
Requires-Dist: cachetools==5.3.3
Requires-Dist: certifi==2025.1.31
Requires-Dist: click==8.1.8
Requires-Dist: colorama==0.4.6
Requires-Dist: connexity==0.0.8
Requires-Dist: distro==1.9.0
Requires-Dist: dnspython==2.7.0
Requires-Dist: email_validator==2.2.0
Requires-Dist: fastapi==0.111.0
Requires-Dist: fastapi-cli==0.0.7
Requires-Dist: fireworks-ai==0.15.12
Requires-Dist: google-cloud-aiplatform>=1.38
Requires-Dist: groq==0.9.0
Requires-Dist: h11==0.14.0
Requires-Dist: httpcore==1.0.7
Requires-Dist: httptools==0.6.4
Requires-Dist: httpx==0.28.1
Requires-Dist: httpx-sse==0.4.0
Requires-Dist: httpx-ws==0.7.1
Requires-Dist: idna==3.10
Requires-Dist: Jinja2==3.1.5
Requires-Dist: loguru==0.7.3
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: MarkupSafe==3.0.2
Requires-Dist: mdurl==0.1.2
Requires-Dist: noisereduce==3.0.3
Requires-Dist: openai==1.70.0
Requires-Dist: orjson==3.10.15
Requires-Dist: pipecat-ai[cartesia,daily,deepgram,lmnt,openai,silero]==0.0.67
Requires-Dist: pillow==11.1.0
Requires-Dist: pydantic==2.10.6
Requires-Dist: pydantic_core==2.27.2
Requires-Dist: pydub==0.25.1
Requires-Dist: pyht==0.1.14
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: python-multipart==0.0.20
Requires-Dist: PyYAML==6.0.2
Requires-Dist: Pygments==2.19.1
Requires-Dist: requests~=2.32.3
Requires-Dist: rich==13.9.4
Requires-Dist: rich-toolkit==0.13.2
Requires-Dist: shellingham==1.5.4
Requires-Dist: sniffio==1.3.1
Requires-Dist: soundfile==0.13.1
Requires-Dist: starlette==0.37.2
Requires-Dist: tqdm==4.67.1
Requires-Dist: twilio==9.6.0
Requires-Dist: typer==0.15.1
Requires-Dist: typing_extensions==4.12.2
Requires-Dist: ujson==5.10.0
Requires-Dist: uvicorn==0.32.1
Requires-Dist: watchfiles==1.0.4
Requires-Dist: websockets==13.1
Requires-Dist: wsproto==1.2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocstrings; extra == "docs"
Dynamic: license-file

# Agent Zero

**Agent Zero** is a flexible voice agent framework designed for automated outbound calling, real-time inference, and multi-agent orchestration.  
It supports OpenAI, Gemini, Groq, Fireworks, and other LLMs, with full telephony support via Twilio and Pipecat.

---

## 📦 Installation

Install the latest stable release from PyPI:

```bash
pip install agent-zero
```

Or, if you want to install with development and documentation dependencies:

```bash
pip install "agent-zero[dev,docs]"
```

---

## 🚀 Quick Start

You can import and use the core setup functions as follows:

```python
from agent_zero import init_config
from agent_zero import register_custom_tools
from agent_zero import register_routes, register_custom_handlers
```

---

## 🧩 Example Usage

```python
from pathlib import Path
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from agent_zero import init_config
from agent_zero import register_custom_tools
from agent_zero import register_routes, register_custom_handlers

PROJECT_ROOT = Path(__file__).parent
CONFIG_PATH = PROJECT_ROOT / "config.yaml"
HANDLERS_PATH = str(PROJECT_ROOT / "custom/handlers")
TOOLS_CONFIG_PATH = str(PROJECT_ROOT / "custom/tools/config.yaml")
TOOLS_FUNCTIONS_PATH = str(PROJECT_ROOT / "custom/tools/functions")

init_config(str(CONFIG_PATH))
register_custom_handlers(HANDLERS_PATH)
register_custom_tools(TOOLS_FUNCTIONS_PATH, TOOLS_CONFIG_PATH)

app = FastAPI()
register_routes(app)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

---

## 🔧 Configuration

Each project must provide a `config.yaml` file with the following structure:

```yaml
vad_params:
  confidence: 0.5
  min_volume: 0.6
  start_secs: 0.2
  stop_secs: 0.8

llm:
  main:
    vendor: "openai"
    model: "gpt-4.1-mini-2025-04-14"
  utils:
    vendor: "openai"
    model: "gpt-4.1-mini-2025-04-14"

vector_db:
  type: "Weaviate"

embedding:
  type: "OpenAI/text-embedding-3-small"

agent_inputs:
  project_name: agent_zero
  language_code: en
  language: English
  translate_prompt: false
  agent_name: Emma
  agent_company_name: SpaceStep

tools: ["greet_user"]
agent_id:
  agent_zero_dev

routes:
  routers:
    - prefix: /agent_zero
      routes:
        - path: /
          methods: [POST]
          handler: agent_inference
        ...
  websockets:
    - prefix: /agent_zero
      routes:
        - path: /outbound/ws
          handler: outbound_websocket_endpoint
```

---

## 🛠️ Tool Configuration

Each tool must be declared in the `tools` section of `config.yaml` and implemented inside `functions/`.

Example `tools/config.yaml`:

```yaml
greet_user:
  description: "Say hello to a user by name."
  parameters:
    type: object
    properties:
      name:
        type: string
        description: "User's first name."
    required: ["name"]
```

---

## 🌐 Environment Variables

Define your API keys and runtime secrets in `.env`:

```env
OPENAI_API_KEY=
GROQ_API_KEY=
FIREWORKS_API_KEY=
GOOGLE_CREDENTIALS_JSON=

# Tooling
TOOL_CHECK_SLOT_AVAILABILITY_WEBHOOK_URL=
TOOL_BOOKING_WEBHOOK_URL=

# Audio + Voice
DEEPGRAM_API_KEY=
ELEVENLABS_API_KEY=
ELEVENLABS_VOICE_ID=

# Twilio
TWILIO_ACCOUNT_ID=
TWILIO_AUTH_TOKEN=
TWILIO_PHONE_NUMBER=
SERVER_ADDRESS=
CALL_STATUS_URL=

# Inference service
INFERENCE_URL=
CONNEXITY_API_KEY=
```

---

## 🧱 Directory Structure

```
src/agent_zero/
├── core/                 # Runtime core: agents, tools, config, models
│   ├── tools/            # Built-in tools and tool manager
│   ├── llm/              # LLM model implementations (OpenAI, Gemini, etc.)
│   ├── pipecat_w_twillio # Pipecat + Twilio integration
│   ├── config.py         # YAML config parser
│   ├── prompts.py        # Prompt loading utilities
│   └── agent.py          # Main agent logic
├── api/                  # FastAPI routes and custom handlers
│   ├── handlers.py       # Handler implementations
│   └── router.py         # Route registration from config
├── data/                 # Schemas, cache, and validators
├── helpers/              # Runtime utilities
├── assets/               # Background audio / SFX
```

---

## 📄 License

MIT License. See `LICENSE`.
