agentex-sdk 0.6.5__tar.gz → 0.6.7__tar.gz

agentex_sdk-0.6.7/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.7"
+}

{agentex_sdk-0.6.5 → agentex_sdk-0.6.7}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.6.7 (2025-11-19)
+
+Full Changelog: [v0.6.6...v0.6.7](https://github.com/scaleapi/scale-agentex-python/compare/v0.6.6...v0.6.7)
+
+## 0.6.6 (2025-11-12)
+
+Full Changelog: [v0.6.5...v0.6.6](https://github.com/scaleapi/scale-agentex-python/compare/v0.6.5...v0.6.6)
+
+### Bug Fixes
+
+* compat with Python 3.14 ([9a62f23](https://github.com/scaleapi/scale-agentex-python/commit/9a62f23376ef797bafe67f61552eb7635286caa3))
+* **compat:** update signatures of `model_dump` and `model_dump_json` for Pydantic v1 ([cf857f9](https://github.com/scaleapi/scale-agentex-python/commit/cf857f9191f10a971e9cba2a8c764229ed4a7dfe))
+
+
+### Chores
+
+* **internal:** restore stats ([5ec0383](https://github.com/scaleapi/scale-agentex-python/commit/5ec0383d9d6a85b342263ba49b8e3893924c59fc))
+* **package:** drop Python 3.8 support ([3d4dc37](https://github.com/scaleapi/scale-agentex-python/commit/3d4dc37f87b8d8f1debbe6505746342e461772ba))
+
 ## 0.6.5 (2025-11-06)
 
 Full Changelog: [v0.6.4...v0.6.5](https://github.com/scaleapi/scale-agentex-python/compare/v0.6.4...v0.6.5)

{agentex_sdk-0.6.5 → agentex_sdk-0.6.7}/CONTRIBUTING.md

@@ -131,28 +131,3 @@ the environment.
 
 This repository is setup with some pre-canned prompts for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as well as [Cursor](https://cursor.com/).
 
-### Cursor
-
-Access to Cursor can be acquired by asking for it in #it-help.  Then just loading this repo in the Cursor IDE should enable the prompts.
-
-### Claude Code
-
-### 1. Install Claude Code
-```bash
-npm install -g @anthropic-ai/claude-code
-```
-
-### 2. Request a LiteLLM API Key
-Visit the [LiteLLM User Guide](https://scale.atlassian.net/wiki/spaces/EPD/pages/1490354189/LiteLLM+User+Guide#Requesting-LiteLLM-Key-for-Generic-Usage) to request your API key.
-
-### 3. Set Environment Variables
-```bash
-export ANTHROPIC_AUTH_TOKEN=${LITELLM_PROXY_API_KEY}
-export ANTHROPIC_BASE_URL="https://litellm.ml-serving-internal.scale.com"
-```
-
-### 4. Start Claude Code
-```bash
-claude
-```
-This should be run from inside the main repo directory. If you run the command from a terminal inside VSCode, then Claude will use the VSCode editor to show diffs etc. 

{agentex_sdk-0.6.5 → agentex_sdk-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentex-sdk
-Version: 0.6.5
+Version: 0.6.7
 Summary: The official Python library for the agentex API
 Project-URL: Homepage, https://github.com/scaleapi/scale-agentex-python
 Project-URL: Repository, https://github.com/scaleapi/scale-agentex-python
@@ -55,6 +55,7 @@ Requires-Dist: tzdata>=2025.2
 Requires-Dist: tzlocal>=5.3.1
 Requires-Dist: uvicorn>=0.31.1
 Requires-Dist: watchfiles<1.0,>=0.24.0
+Requires-Dist: yaspin>=3.1.0
 Provides-Extra: aiohttp
 Requires-Dist: aiohttp; extra == 'aiohttp'
 Requires-Dist: httpx-aiohttp>=0.1.9; extra == 'aiohttp'
@@ -68,7 +69,7 @@ Description-Content-Type: text/markdown
 <!-- prettier-ignore -->
 [![PyPI version](https://img.shields.io/pypi/v/agentex-sdk.svg?label=pypi%20(stable))](https://pypi.org/project/agentex-sdk/)
 
-The Agentex Python library provides convenient access to the Agentex REST API from any Python 3.8+
+The Agentex Python library provides convenient access to the Agentex REST API from any Python 3.9+
 application. The library includes type definitions for all request params and response fields,
 and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
 
@@ -453,7 +454,7 @@ print(agentex.__version__)
 
 ## Requirements
 
-Python 3.8 or higher.
+Python 3.9 or higher.
 
 ## Contributing
 

{agentex_sdk-0.6.5 → agentex_sdk-0.6.7}/README.md

@@ -4,7 +4,7 @@
 <!-- prettier-ignore -->
 [![PyPI version](https://img.shields.io/pypi/v/agentex-sdk.svg?label=pypi%20(stable))](https://pypi.org/project/agentex-sdk/)
 
-The Agentex Python library provides convenient access to the Agentex REST API from any Python 3.8+
+The Agentex Python library provides convenient access to the Agentex REST API from any Python 3.9+
 application. The library includes type definitions for all request params and response fields,
 and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
 
@@ -389,7 +389,7 @@ print(agentex.__version__)
 
 ## Requirements
 
-Python 3.8 or higher.
+Python 3.9 or higher.
 
 ## Contributing
 

agentex_sdk-0.6.7/examples/demos/procurement_agent/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# UV
+.venv/
+uv.lock

agentex_sdk-0.6.7/examples/demos/procurement_agent/Dockerfile

@@ -0,0 +1,48 @@
+# syntax=docker/dockerfile:1.3
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.6.4 /uv /uvx /bin/
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    htop \
+    vim \
+    curl \
+    tar \
+    python3-dev \
+    postgresql-client \
+    build-essential \
+    libpq-dev \
+    gcc \
+    cmake \
+    netcat-openbsd \
+    nodejs \
+    npm \ 
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/**
+
+# Install tctl (Temporal CLI)
+RUN curl -L https://github.com/temporalio/tctl/releases/download/v1.18.1/tctl_1.18.1_linux_arm64.tar.gz -o /tmp/tctl.tar.gz && \
+    tar -xzf /tmp/tctl.tar.gz -C /usr/local/bin && \
+    chmod +x /usr/local/bin/tctl && \
+    rm /tmp/tctl.tar.gz
+
+RUN uv pip install --system --upgrade pip setuptools wheel
+
+ENV UV_HTTP_TIMEOUT=1000
+
+# Copy just the pyproject.toml file to optimize caching
+COPY procurement_agent/pyproject.toml /app/procurement_agent/pyproject.toml
+
+WORKDIR /app/procurement_agent
+
+# Install the required Python packages using uv
+RUN uv pip install --system .
+
+# Copy the project code
+COPY procurement_agent/project /app/procurement_agent/project
+
+# Run the ACP server using uvicorn
+CMD ["uvicorn", "project.acp:acp", "--host", "0.0.0.0", "--port", "8000"]
+
+# When we deploy the worker, we will replace the CMD with the following
+# CMD ["python", "-m", "run_worker"] 

agentex_sdk-0.6.7/examples/demos/procurement_agent/README.md

@@ -0,0 +1,412 @@
+# Procurement Agent Demo
+
+A demonstration of long-running, autonomous AI agents using **Temporal** and **AgentEx**. This agent manages construction procurement workflows that can run for months, respond to external events, and escalate to humans when needed.
+
+## What This Demo Shows
+
+This demo illustrates a **procurement manager for building construction** that:
+
+- **Runs for months or years** - Temporal workflows enable truly persistent agents
+- **Responds to external events** - Not just human input, but signals from the real world (shipments, inspections, etc.)
+- **Escalates to humans when needed** - Waits indefinitely for human decisions on critical issues
+- **Learns from experience** - Remembers past human decisions and applies them to similar situations
+- **Manages complex state** - Uses a database to track construction schedules and procurement items
+
+### Key Concepts
+
+**Long-Running Workflows**: Thanks to Temporal, the agent can live for months, surviving restarts and failures while maintaining full context.
+
+**External Event Integration**: The agent receives real-world signals (not just user messages) via Temporal signals and takes autonomous actions.
+
+**Human-in-the-Loop**: The agent can pause execution indefinitely (up to 24 hours) while waiting for human approval on critical decisions.
+
+**Learning System**: When a human makes a decision, the agent extracts learnings and applies them to future similar situations.
+
+**State Management**: Uses SQLite to persist construction schedules and procurement item status, providing queryable visibility into current operations without parsing conversation history.
+
+**Automatic Summarization**: When conversation history exceeds token limits (~40k tokens), the agent automatically summarizes older messages while preserving recent context, enabling indefinite conversation length.
+
+## Example Workflow
+
+Here's what happens when items move through the procurement pipeline:
+
+1. **Submittal Approved** → Agent issues purchase order and creates tracking record
+2. **Shipment Departed Factory** → Agent ingests ETA and checks for schedule conflicts
+3. **Shipment Arrived Site** → Agent notifies team and schedules quality inspection
+4. **Inspection Failed** → Agent escalates to human with recommended action
+5. **Human Decision** → Agent learns from the decision for next time
+
+## Running the Demo
+
+### Prerequisites
+
+You'll need three terminals running:
+
+1. **AgentEx Backend** (database, Temporal server, etc.)
+2. **AgentEx UI** (web interface at localhost:3000)
+3. **Procurement Agent** (this demo)
+
+### Step 1: Start AgentEx Backend
+
+From the `scale-agentex` repository:
+
+```bash
+make dev
+```
+
+This starts all required services (Postgres, Temporal, Redis, etc.) via Docker Compose. Verify everything is healthy:
+
+```bash
+# Optional: Use lazydocker for a better view
+lzd
+```
+
+You should see Temporal UI at: http://localhost:8080
+
+### Step 2: Start AgentEx Web UI
+
+From the `scale-agentex-web` repository:
+
+```bash
+make dev
+```
+
+The UI will be available at: http://localhost:3000
+
+### Step 3: Run the Procurement Agent
+
+From this directory (`examples/demos/procurement_agent`):
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the agent
+export ENVIRONMENT=development && uv run agentex agents run --manifest manifest.yaml
+```
+
+The agent will start and register with the AgentEx backend on port 8000.
+
+### Step 4: Create a Task
+
+Go to http://localhost:3000 and:
+
+1. Create a new task for the `procurement-agent`
+2. Send a message like "Hello" to initialize the workflow
+3. Note the **Workflow ID** from the Temporal UI at http://localhost:8080
+
+### Step 5: Send Test Events
+
+Now simulate real-world procurement events:
+
+```bash
+# Navigate to the scripts directory
+cd project/scripts
+
+# Send events (you'll be prompted for the workflow ID)
+uv run send_test_events.py
+
+# Or provide the workflow ID directly
+uv run send_test_events.py <workflow-id>
+```
+
+The script sends a series of events simulating the procurement lifecycle for multiple items:
+- Steel Beams (passes inspection)
+- HVAC Units (fails inspection - agent escalates)
+- Windows (passes inspection)
+- Flooring Materials (passes inspection)
+- Electrical Panels (fails inspection - agent applies learnings)
+
+### Step 6: Observe the Agent
+
+Watch the agent in action:
+
+1. **AgentEx UI** (http://localhost:3000) - See agent responses and decisions
+2. **Temporal UI** (http://localhost:8080) - View workflow execution, signals, and state
+3. **Terminal** - Watch agent logs for detailed operation info
+
+When an inspection fails, the agent will:
+- Analyze the situation
+- Recommend an action
+- Wait for your response in the AgentEx UI
+- Learn from your decision for future similar situations
+
+## Project Structure
+
+```
+procurement_agent/
+├── project/
+│   ├── acp.py                          # ACP server & event handlers
+│   ├── workflow.py                     # Main Temporal workflow logic
+│   ├── run_worker.py                   # Temporal worker setup
+│   ├── agents/
+│   │   ├── procurement_agent.py        # Main AI agent with procurement tools
+│   │   ├── extract_learnings_agent.py  # Extracts learnings from human decisions
+│   │   └── summarization_agent.py      # Summarizes conversation history
+│   ├── activities/
+│   │   └── activities.py               # Temporal activities (POs, inspections, schedules)
+│   ├── data/
+│   │   ├── database.py                 # SQLite operations
+│   │   └── procurement.db              # Persistent storage (auto-created)
+│   ├── models/
+│   │   └── events.py                   # Event type definitions (Pydantic models)
+│   ├── scripts/
+│   │   └── send_test_events.py         # Event simulation script
+│   └── utils/
+│       ├── learning_extraction.py      # Utilities for extracting context from conversations
+│       └── summarization.py            # Token counting and summarization logic
+├── manifest.yaml                       # Agent configuration
+├── Dockerfile                          # Container definition
+└── pyproject.toml                      # Dependencies (uv)
+```
+
+## How It Works
+
+### 1. Event-Driven Architecture
+
+The agent receives events via Temporal signals in `workflow.py`:
+
+```python
+@workflow.signal
+async def send_event(self, event: str) -> None:
+    # Validate and queue the event
+    await self.event_queue.put(event)
+```
+
+Events are validated against Pydantic models and processed by the AI agent.
+
+### 2. Human-in-the-Loop Pattern
+
+Critical decisions require human approval via the `wait_for_human` tool in `procurement_agent.py`:
+
+```python
+@function_tool
+async def wait_for_human(recommended_action: str) -> str:
+    """
+    Pause execution until human provides input.
+    Waits up to 24 hours for response.
+    """
+    await workflow.wait_condition(
+        lambda: not workflow_instance.human_queue.empty(),
+        timeout=timedelta(hours=24),
+    )
+    # ... return human response
+```
+
+The workflow continues only after receiving human input through the AgentEx UI.
+
+### 3. State Management
+
+Instead of cramming everything into the LLM context window, the agent uses SQLite to manage:
+
+- **Master construction schedule** (delivery dates, buffer days, requirements)
+- **Procurement items** (status, ETAs, purchase orders, inspection results)
+
+The database is accessed through Temporal activities with proper error handling and retry policies.
+
+### 4. Learning System
+
+When humans make decisions, the agent extracts learnings in `extract_learnings_agent.py`:
+
+```python
+# After human input, extract the learning
+extraction_result = await Runner.run(extract_agent, new_context, hooks=hooks)
+learning = extraction_result.final_output
+
+# Store in workflow state for future reference
+self.human_input_learnings.append(learning)
+```
+
+These learnings are passed into the agent's system prompt on subsequent runs.
+
+### 5. Automatic Summarization
+
+For long-running workflows, conversation history can grow unbounded. The agent automatically manages context using intelligent summarization:
+
+```python
+# After each turn, check if summarization is needed
+if should_summarize(self._state.input_list):
+    # Find messages to summarize (preserves last 10 turns, starts after previous summary)
+    messages_to_summarize, start_index, end_index = get_messages_to_summarize(
+        self._state.input_list,
+        last_summary_index
+    )
+
+    # Generate summary with dedicated agent
+    summary_agent = new_summarization_agent()
+    summary_result = await Runner.run(summary_agent, messages_to_summarize, hooks=hooks)
+
+    # Replace summarized portion with compact summary
+    self._state.input_list = apply_summary_to_input_list(...)
+```
+
+Key features:
+- **Token threshold**: Triggers at ~40k tokens to stay within model limits
+- **Preserves recent context**: Always keeps last 10 user turns in full detail
+- **Never re-summarizes**: Starts after the most recent summary to avoid information loss
+- **Dedicated summarization agent**: GPT-4o agent focused on extracting key procurement events, decisions, and current state
+
+This enables workflows to run indefinitely without hitting context limits.
+
+### 6. Error Handling & Retries
+
+The workflow uses Temporal's retry policies for resilient execution:
+
+```python
+retry_policy = RetryPolicy(
+    initial_interval=timedelta(seconds=1),
+    backoff_coefficient=2.0,  # Exponential backoff
+    maximum_interval=timedelta(seconds=120),
+    maximum_attempts=5,
+    non_retryable_error_types=[
+        "DataCorruptionError",
+        "ScheduleNotFoundError",
+    ]
+)
+```
+
+Activities automatically retry on transient failures but fail fast on data corruption.
+
+## Key Features
+
+### Durability
+- Workflows survive process restarts, crashes, and deployments
+- All state is persisted in Temporal and SQLite
+- No context is lost even after months of runtime
+
+### External Event Processing
+- Responds to events from external systems (ERP, logistics, QA)
+- Validates and processes events asynchronously
+- Multiple event types supported (approvals, shipments, inspections)
+
+### Human Escalation
+- Automatically escalates critical issues (schedule delays, inspection failures)
+- Provides recommended actions to humans
+- Waits indefinitely (up to 24 hours) for human response
+- Continues workflow after receiving guidance
+
+### Learning & Adaptation
+- Extracts patterns from human decisions
+- Applies learned rules to similar future situations
+- Becomes more autonomous over time
+- Human maintains oversight and final authority
+
+### Observability
+- Full workflow history in Temporal UI
+- Real-time agent responses in AgentEx UI
+- Detailed logging for debugging
+- Database audit trail for all changes
+
+## Customizing the Demo
+
+### Modify the Construction Schedule
+
+Edit the default schedule in `project/data/database.py`:
+
+```python
+DEFAULT_SCHEDULE = {
+    "project": {
+        "name": "Small Office Renovation",
+        "start_date": "2026-02-01",
+        "end_date": "2026-05-31"
+    },
+    "deliveries": [
+        {
+            "item": "Steel Beams",
+            "required_by": "2026-02-15",
+            "buffer_days": 5
+        },
+        # ... add more items
+    ]
+}
+```
+
+### Add New Event Types
+
+1. Define the event in `project/models/events.py`
+2. Update event validation in `workflow.py`
+3. Teach the agent how to handle it in `procurement_agent.py`
+4. Add test events in `project/scripts/send_test_events.py`
+
+### Change Agent Behavior
+
+Modify the agent's instructions in `project/agents/procurement_agent.py`:
+
+```python
+def new_procurement_agent(master_construction_schedule: str, human_input_learnings: list) -> Agent:
+    instructions = f"""
+    You are a procurement agent for a commercial building construction project.
+
+    [Your custom instructions here...]
+    """
+    # ...
+```
+
+### Add New Tools
+
+Create new activities in `project/activities/activities.py` and register them as tools:
+
+```python
+@activity.defn(name="my_custom_activity")
+async def my_custom_activity(param: str) -> str:
+    # ... your logic
+    return result
+
+# Register in the agent
+tools=[
+    openai_agents.workflow.activity_as_tool(
+        my_custom_activity,
+        start_to_close_timeout=timedelta(minutes=10)
+    ),
+    # ... other tools
+]
+```
+
+## Troubleshooting
+
+**Agent not appearing in UI**
+- Verify agent is running on port 8000: `lsof -i :8000`
+- Check `ENVIRONMENT=development` is set
+- Review agent logs for errors
+
+**Events not being received**
+- Confirm workflow ID is correct (check Temporal UI)
+- Verify Temporal server is running: `docker ps | grep temporal`
+- Check that send_test_events.py is using the right workflow ID
+
+**Human escalation timeout**
+- The agent waits 24 hours for human input before timing out
+- Respond in the AgentEx UI task thread
+- Check that your message is being sent to the correct task
+
+**Database errors**
+- The database is automatically created at `project/data/procurement.db`
+- Delete the file to reset: `rm project/data/procurement.db`
+- The agent will recreate it on next run
+
+**Import errors**
+- Make sure dependencies are installed: `uv sync`
+- Verify you're running from the correct directory
+- Check Python version is 3.12+
+
+## What's Next?
+
+This demo shows the foundation for autonomous, long-running agents. Potential applications include:
+
+- **Supply chain management** - Track orders, shipments, and inventory across months
+- **Compliance workflows** - Monitor regulatory requirements and schedule audits
+- **Customer success** - Proactive outreach based on usage patterns and lifecycle stage
+- **Infrastructure management** - React to alerts, coordinate maintenance, escalate outages
+- **Financial processes** - Invoice approval workflows, budget tracking, expense management
+
+The key insight: **AI agents don't just answer questions—they can run real-world processes autonomously over time.**
+
+## Learn More
+
+- [AgentEx Documentation](https://agentex.sgp.scale.com/docs/)
+- [Temporal Documentation](https://docs.temporal.io/)
+- [OpenAI Agents SDK](https://github.com/openai/agents-sdk)
+
+---
+
+**Questions or issues?** Open an issue on the [scale-agentex GitHub repository](https://github.com/scaleapi/scale-agentex).