Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion examples/tutorials/00_sync/000_hello_acp/manifest.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ agent:

# Type of ACP to use
# sync: Simple synchronous ACP implementation
# agentic: Advanced ACP with sub-types "base" or "temporal" (requires config)
# async: Asynchronous, non-blocking ACP implementation
acp_type: sync

# Description of what your agent does
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,6 @@ Three handlers instead of one, giving you full control over task lifecycle. Task
- Building towards production systems

## Why This Matters
The task-based model is the foundation of production agents. Unlike sync agents where each message is independent, agentic agents maintain persistent tasks that can receive multiple events, store state, and have full lifecycle management. This is the stepping stone to Temporal-based agents.
The task-based model is the foundation of production agents. Unlike sync agents where each message is independent, async agents maintain persistent tasks that can receive multiple events, store state, and have full lifecycle management. This is the stepping stone to Temporal-based agents.

**Next:** [010_multiturn](../010_multiturn/) - Add conversation memory
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ deployment:
global:
agent:
name: "ab000-hello-acp"
description: "An AgentEx agent that is not intelligent. It just shows how to implement the base agentic ACP type."
description: "An AgentEx agent that is not intelligent. It just shows how to implement the base async ACP type."

# Default replica count
replicaCount: 1
Expand Down
12 changes: 6 additions & 6 deletions examples/tutorials/10_async/00_base/010_multiturn/README.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
# [Agentic] Multiturn
# [Async] Multiturn

Handle multi-turn conversations in agentic agents with task-based state management. Each task maintains its own conversation history automatically.
Handle multi-turn conversations in async agents with task-based state management. Each task maintains its own conversation history automatically.

## What You'll Learn
- How tasks maintain conversation state across multiple exchanges
- Difference between sync and agentic multiturn patterns
- Difference between sync and async multiturn patterns
- Building stateful conversational agents with minimal code

## Prerequisites
- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
- Backend services running: `make dev` from repository root
- Understanding of basic agentic agents (see [000_hello_acp](../000_hello_acp/))
- Understanding of basic async agents (see [000_hello_acp](../000_hello_acp/))

## Quick Start

```bash
cd examples/tutorials/10_agentic/00_base/010_multiturn
cd examples/tutorials/10_async/00_base/010_multiturn
uv run agentex agents run --manifest manifest.yaml
```

## Key Pattern

Unlike sync agents where you manually track conversation history, agentic agents automatically maintain state within each task:
Unlike sync agents where you manually track conversation history, async agents automatically maintain state within each task:

```python
@app.on_task_event_send()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
"metadata": {},
"outputs": [],
"source": [
"# (REQUIRED) Create a new task. For Agentic agents, you must create a task for messages to be associated with.\n",
"# (REQUIRED) Create a new task. For Async agents, you must create a task for messages to be associated with.\n",
"import uuid\n",
"\n",
"rpc_response = client.agents.create_task(\n",
Expand Down
10 changes: 5 additions & 5 deletions examples/tutorials/10_async/00_base/020_streaming/README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
# [Agentic] Streaming

Stream responses in agentic agents using `adk.messages.create()` to send progressive updates. More flexible than sync streaming since you can send multiple messages at any time.
Stream responses in async agents using `adk.messages.create()` to send progressive updates. More flexible than sync streaming since you can send multiple messages at any time.

## What You'll Learn
- How to stream with explicit message creation
- Difference between sync and agentic streaming patterns
- Difference between sync and async streaming patterns
- When to send multiple messages vs single streamed response

## Prerequisites
- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
- Backend services running: `make dev` from repository root
- Understanding of agentic basics (see [000_hello_acp](../000_hello_acp/))
- Understanding of async basics (see [000_hello_acp](../000_hello_acp/))

## Quick Start

```bash
cd examples/tutorials/10_agentic/00_base/020_streaming
cd examples/tutorials/10_async/00_base/020_streaming
uv run agentex agents run --manifest manifest.yaml
```

Expand All @@ -33,7 +33,7 @@ async def handle_event_send(params: SendEventParams):
await adk.messages.create(task_id=task_id, content=...)
```

Unlike sync streaming (which uses async generators), agentic streaming uses explicit message creation calls, giving you more control over when and what to send.
Unlike sync streaming (which uses async generators), async streaming uses explicit message creation calls, giving you more control over when and what to send.

## When to Use
- Multi-step processes with intermediate results
Expand Down
4 changes: 2 additions & 2 deletions examples/tutorials/10_async/00_base/030_tracing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ Add observability to your agents with spans and traces using `adk.tracing.start_
## Prerequisites
- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
- Backend services running: `make dev` from repository root
- Understanding of agentic agents (see [000_hello_acp](../000_hello_acp/))
- Understanding of async agents (see [000_hello_acp](../000_hello_acp/))

## Quick Start

```bash
cd examples/tutorials/10_agentic/00_base/030_tracing
cd examples/tutorials/10_async/00_base/030_tracing
uv run agentex agents run --manifest manifest.yaml
```

Expand Down
4 changes: 2 additions & 2 deletions examples/tutorials/10_async/00_base/040_other_sdks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ Agents are just Python code - integrate any SDK you want (OpenAI, Anthropic, Lan
## Prerequisites
- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
- Backend services running: `make dev` from repository root
- Understanding of agentic agents (see [000_hello_acp](../000_hello_acp/))
- Understanding of async agents (see [000_hello_acp](../000_hello_acp/))

## Quick Start

```bash
cd examples/tutorials/10_agentic/00_base/040_other_sdks
cd examples/tutorials/10_async/00_base/040_other_sdks
uv run agentex agents run --manifest manifest.yaml
```

Expand Down
12 changes: 6 additions & 6 deletions examples/tutorials/10_async/00_base/080_batch_events/README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# [Agentic] Batch Events

Demonstrates limitations of the base agentic protocol with concurrent event processing. When multiple events arrive rapidly, base agentic agents handle them sequentially, which can cause issues.
Demonstrates limitations of the base async protocol with concurrent event processing. When multiple events arrive rapidly, base async agents handle them sequentially, which can cause issues.

## What You'll Learn
- Limitations of non-Temporal agentic agents
- Limitations of non-Temporal async agents
- Race conditions and ordering issues in concurrent scenarios
- When you need workflow orchestration
- Why this motivates Temporal adoption

## Prerequisites
- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
- Backend services running: `make dev` from repository root
- Understanding of agentic patterns (see previous tutorials)
- Understanding of async patterns (see previous tutorials)

## Quick Start

```bash
cd examples/tutorials/10_agentic/00_base/080_batch_events
cd examples/tutorials/10_async/00_base/080_batch_events
uv run agentex agents run --manifest manifest.yaml
```

Expand All @@ -27,15 +27,15 @@ This tutorial shows **when you need Temporal**. If your agent needs to:
- Process multiple events in parallel safely
- Maintain consistent state under concurrent load

Then you should use Temporal workflows (see tutorials 10_agentic/10_temporal/) which provide:
Then you should use Temporal workflows (see tutorials 10_async/10_temporal/) which provide:
- Deterministic event ordering
- Safe concurrent processing
- Guaranteed state consistency

This is the "breaking point" tutorial that motivates moving to Temporal for production agents.

## When to Use (This Pattern)
This tutorial shows what NOT to use for production. Use base agentic agents only when:
This tutorial shows what NOT to use for production. Use base async agents only when:
- Events are infrequent (< 1 per second)
- Order doesn't matter
- State consistency isn't critical
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,13 @@ The system uses a shared build configuration with type-safe interfaces:
- Backend services running: `make dev` from repository root
- Python 3.12+ and uv package manager
- OpenAI API key (set `OPENAI_API_KEY` or create `.env` file)
- Understanding of agentic patterns (see previous tutorials)
- Understanding of async patterns (see previous tutorials)

### Running the System

1. **Start all agents**:
```bash
cd examples/tutorials/10_agentic/00_base/090_multi_agent_non_temporal
cd examples/tutorials/10_async/00_base/090_multi_agent_non_temporal
./start-agents.sh start
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ CRITIC_PORT=8002
FORMATTER_PORT=8003

# Base directory
BASE_DIR="examples/tutorials/10_agentic/00_base/090_multi_agent_non_temporal"
BASE_DIR="examples/tutorials/10_async/00_base/090_multi_agent_non_temporal"

echo -e "${BLUE}🎭 Multi-Agent Content Assembly Line (Flattened)${NC}"
echo -e "${BLUE}===============================================${NC}"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,18 @@ Temporal workflows make agents durable - they survive restarts and can run indef
- Building durable agents with Temporal workflows
- The workflow and signal pattern
- How workflows survive failures and resume automatically
- When to use Temporal vs base agentic agents
- When to use Temporal vs base async agents

## Prerequisites
- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
- Backend services running: `make dev` from repository root (includes Temporal)
- Temporal UI available at http://localhost:8233
- Understanding of base agentic agents (see [../../00_base/080_batch_events](../../00_base/080_batch_events/) to understand why Temporal)
- Understanding of base async agents (see [../../00_base/080_batch_events](../../00_base/080_batch_events/) to understand why Temporal)

## Quick Start

```bash
cd examples/tutorials/10_agentic/10_temporal/000_hello_acp
cd examples/tutorials/10_async/10_temporal/000_hello_acp
uv run agentex agents run --manifest manifest.yaml
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Combine streaming responses, multi-turn chat, tool calling, and tracing - all wi
## Quick Start

```bash
cd examples/tutorials/10_agentic/10_temporal/010_agent_chat
cd examples/tutorials/10_async/10_temporal/010_agent_chat
uv run agentex agents run --manifest manifest.yaml
```

Expand All @@ -33,7 +33,7 @@ uv run agentex agents run --manifest manifest.yaml

## Key Insight

In base agentic agents, all this state lives in memory and is lost on crash. With Temporal, the entire conversation - history, tool calls, intermediate state - is durably persisted. The agent can pick up a conversation that paused days ago as if no time passed.
In base async agents, all this state lives in memory and is lost on crash. With Temporal, the entire conversation - history, tool calls, intermediate state - is durably persisted. The agent can pick up a conversation that paused days ago as if no time passed.

## When to Use
- Production chatbots with tool capabilities
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ async def on_task_event_send(self, params: SendEventParams) -> None:
"to provide accurate and well-reasoned responses."
),
parent_span_id=span.id if span else None,
model="gpt-5-mini",
model="gpt-4o-mini",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

intentional?

model_settings=ModelSettings(
# Include reasoning items in the response (IDs, summaries)
# response_include=["reasoning.encrypted_content"],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
- Multi-turn conversations with state management
- Tool usage (calculator and web search via MCP)

Key differences from base agentic (040_other_sdks):
Key differences from base async (040_other_sdks):
1. Temporal Integration: Uses Temporal workflows for durable execution
2. State Management: State is managed within the workflow instance
3. No Race Conditions: Temporal ensures sequential event processing
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Build complex multi-state workflows using state machines with Temporal. This tut
## Quick Start

```bash
cd examples/tutorials/10_agentic/10_temporal/020_state_machine
cd examples/tutorials/10_async/10_temporal/020_state_machine
uv run agentex agents run --manifest manifest.yaml
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ agent:

# Description of what your agent does
# Helps with documentation and discovery
description: An AgentEx agentthat demonstrates how to uose state machines to manage complex agentic workflows
description: An AgentEx agentthat demonstrates how to uose state machines to manage complex async workflows

# Temporal workflow configuration
# This enables your agent to run as a Temporal workflow for long-running tasks
Expand Down Expand Up @@ -122,7 +122,7 @@ deployment:
global:
agent:
name: "at020-state-machine"
description: "An AgentEx agentthat demonstrates how to uose state machines to manage complex agentic workflows"
description: "An AgentEx agentthat demonstrates how to uose state machines to manage complex async workflows"

# Default replica count
replicaCount: 1
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ build-backend = "hatchling.build"
[project]
name = "at020-state-machine"
version = "0.1.0"
description = "An AgentEx agentthat demonstrates how to uose state machines to manage complex agentic workflows"
description = "An AgentEx agentthat demonstrates how to uose state machines to manage complex async workflows"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Learn how to extend Temporal workflows with custom activities for external opera

**Terminal 1 - Start Worker:**
```bash
cd examples/tutorials/10_agentic/10_temporal/030_custom_activities
cd examples/tutorials/10_async/10_temporal/030_custom_activities
uv run python project/run_worker.py
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ This tutorial demonstrates how to implement streaming multiturn tool-enabled cha
## Quick Start

```bash
cd examples/tutorials/10_agentic/10_temporal/050_agent_chat_guardrails
cd examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails
uv run agentex agents run --manifest manifest.yaml
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# Create the ACP server
acp = FastACP.create(
acp_type="agentic",
acp_type="async",
config=TemporalACPConfig(
# When deployed to the cluster, the Temporal address will automatically be set to the cluster address
# For local development, we set the address manually to talk to the local Temporal service set up via docker compose
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,7 @@
"id": "d1c309d6",
"metadata": {},
"outputs": [],
"source": [
"AGENT_NAME = \"example-tutorial\""
]
"source": "AGENT_NAME = \"at060-open-ai-agents-sdk-hello-world\""
},
{
"cell_type": "code",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ agent:

# Unique name for your agent
# Used for task routing and monitoring
name: example-tutorial
name: at060-open-ai-agents-sdk-hello-world

# Description of what your agent does
# Helps with documentation and discovery
Expand All @@ -82,12 +82,12 @@ agent:
workflows:
# Name of the workflow class
# Must match the @workflow.defn name in your workflow.py
- name: example-tutorial
- name: at060-open-ai-agents-sdk-hello-world

# Queue name for task distribution
# Used by Temporal to route tasks to your agent
# Convention: <agent_name>_task_queue
queue_name: example_tutorial_queue
queue_name: at060_open_ai_agents_sdk_hello_world_queue

# Optional: Credentials mapping
# Maps Kubernetes secrets to environment variables
Expand All @@ -102,10 +102,10 @@ agent:

# Optional: Set Environment variables for running your agent locally as well
# as for deployment later on
env:
OPENAI_API_KEY: ""
env: {}
# OPENAI_API_KEY: ""
# OPENAI_BASE_URL: "<YOUR_OPENAI_BASE_URL_HERE>"
OPENAI_ORG_ID: ""
# OPENAI_ORG_ID: ""


# Deployment Configuration
Expand All @@ -124,7 +124,7 @@ deployment:
# These can be overridden using --override-file with custom configuration files
global:
agent:
name: "example-tutorial"
name: "at060-open-ai-agents-sdk-hello-world"
description: "An AgentEx agent"

# Default replica count
Expand All @@ -137,4 +137,4 @@ deployment:
memory: "1Gi"
limits:
cpu: "1000m"
memory: "2Gi"
memory: "2Gi"
Loading