Rename acp_type=AGENTIC to ASYNC with backwards compatibility

agentex/database/migrations/alembic/versions/2025_10_30_2157_change_default_acp_to_async_329fbafa4ff9.py

@@ -0,0 +1,42 @@
+"""change_default_acp_to_async
+
+Revision ID: 329fbafa4ff9
+Revises: d7addd4229e8
+Create Date: 2025-10-30 21:57:45.309656
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '329fbafa4ff9'
+down_revision: Union[str, None] = 'd7addd4229e8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    # Change the server_default of acp_type column to "async"
+    op.alter_column(
+        'agents',
+        'acp_type',
+        server_default='async',
+        existing_nullable=False
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    # Revert the server_default of acp_type column back to "agentic"
+    op.alter_column(
+        'agents',
+        'acp_type',
+        server_default='agentic',
+        existing_nullable=False
+    )
+    # ### end Alembic commands ###

agentex/database/migrations/migration_history.txt

@@ -1,4 +1,5 @@
-09368a02d6cc -> d7addd4229e8 (head), soft delete status
+d7addd4229e8 -> 329fbafa4ff9 (head), change_default_acp_to_async
+09368a02d6cc -> d7addd4229e8, soft delete status
 739800d3e1ce -> 09368a02d6cc, deployment history
 dbac39ab82c3 -> 739800d3e1ce, registration metadata
 87454c35c13e -> dbac39ab82c3, add_task_metadata

agentex/docs/docs/acp/agentic/base.md → agentex/docs/docs/acp/async/base.md

@@ -1,6 +1,6 @@
-# Base Agentic ACP
+# Base Async ACP
 
-**Base Agentic ACP** is the foundational implementation designed for learning and development environments. It provides complete control over task lifecycle while using Agentex's built-in state management.
+**Base Async ACP** is the foundational implementation designed for learning and development environments. It provides complete control over task lifecycle while using Agentex's built-in state management.
 
 ## When to Use
 
@@ -25,14 +25,14 @@
 
 ### Not Ideal For:
 
-❌ **Production Critical Systems** - Use Temporal Agentic ACP
+❌ **Production Critical Systems** - Use Temporal Async ACP
 ❌ **Very Large State Requirements** - Consider external storage
 ❌ **Enterprise Durability** - No advanced fault tolerance
 ❌ **High-Scale Operations** - Better suited for development
 
 ## State Management
 
-Base Agentic ACP requires using Agentex's state management system:
+Base Async ACP requires using Agentex's state management system:
 
 ```python
 @acp.on_task_create
@@ -187,7 +187,7 @@ Used in `@acp.on_task_cancel` for cleanup:
 
 ## Next Steps
 
-- **Ready for production?** Learn about [Temporal Agentic ACP](temporal.md)
+- **Ready for production?** Learn about [Temporal Async ACP](temporal.md)
 - **Need to upgrade?** See the [Migration Guide](../../concepts/migration_guide.md)
 - **New to Agentex?** Follow the [Quick Start Guide on GitHub](https://github.com/scaleapi/scale-agentex#quick-start)
 - **Ready to build?** Check out [Base Agentic Tutorials on GitHub](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_agentic/000_base)

agentex/docs/docs/acp/agentic/overview.md → agentex/docs/docs/acp/async/overview.md

@@ -1,10 +1,10 @@
-# Agentic ACP
+# Async ACP
 
-**Agentic ACP** is the powerful, event-driven approach for complex agent interactions. It provides complete control over task lifecycle, state management, and workflows through three distinct handlers.
+**Async ACP** is the powerful, event-driven approach for complex agent interactions. It provides complete control over task lifecycle, state management, and workflows through three distinct handlers.
 
-## What is Agentic ACP?
+## What is Async ACP?
 
-Agentic ACP provides full lifecycle control where:
+Async ACP provides full lifecycle control where:
 
 - You implement **three handler methods** for complete lifecycle management
 - Tasks require **explicit initialization** and cleanup
@@ -13,9 +13,9 @@ Agentic ACP provides full lifecycle control where:
 
 ## Two Implementation Approaches
 
-Agentic ACP can be implemented in two ways:
+Async ACP can be implemented in two ways:
 
-| Aspect | Base Agentic ACP | Temporal Agentic ACP |
+| Aspect | Base Async ACP | Temporal Async ACP |
 |--------|------------------|----------------------|
 | **Best for** | Learning, development, POCs | Production, enterprise |
 | **State Management** | Agentex state APIs | Temporal event sourcing or Agentex state |
@@ -26,7 +26,7 @@ Agentic ACP can be implemented in two ways:
 
 ## Core Architecture
 
-Both Base and Temporal Agentic ACP share the same three-handler pattern:
+Both Base and Temporal Async ACP share the same three-handler pattern:
 
 ```python
 @acp.on_task_create
@@ -68,7 +68,7 @@ graph TD
 
 ## Asynchronous Event Processing
 
-Think of Agentic ACP like a **postal system for agents** - each agent has its own mailbox where events are delivered asynchronously, and agents decide when and how to process their mail.
+Think of Async ACP like a **postal system for agents** - each agent has its own mailbox where events are delivered asynchronously, and agents decide when and how to process their mail.
 
 ### Every Agent Has a Mailbox
 
@@ -148,24 +148,24 @@ async def handle_event_send(params: SendEventParams):
 
 ## Choose Your Implementation
 
-### Base Agentic ACP
+### Base Async ACP
 
 Perfect for learning and development. Use Agentex's built-in state management.
 
-**[→ Read Base Agentic ACP Guide](base.md)**
+**[→ Read Base Async ACP Guide](base.md)**
 
-### Temporal Agentic ACP
+### Temporal Async ACP
 
 Production-ready with durable execution and automatic fault tolerance.
 
-**[→ Read Temporal Agentic ACP Guide](temporal.md)**
+**[→ Read Temporal Async ACP Guide](temporal.md)**
 
 ---
 
 ## Next Steps
 
-- **Getting started?** Learn about [Base Agentic ACP](base.md) first
-- **Ready for production?** Explore [Temporal Agentic ACP](temporal.md)
+- **Getting started?** Learn about [Base Async ACP](base.md) first
+- **Ready for production?** Explore [Temporal Async ACP](temporal.md)
 - **Need to upgrade?** Check the [Migration Guide](../../concepts/migration_guide.md)
 - **New to Agentex?** Follow the [Quick Start Guide on GitHub](https://github.com/scaleapi/scale-agentex#quick-start)
 - **Ready to build?** Check out [Agentic Tutorials on GitHub](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_agentic)

agentex/docs/docs/acp/agentic/temporal.md → agentex/docs/docs/acp/async/temporal.md

@@ -1,6 +1,6 @@
-# Temporal Agentic ACP
+# Temporal Async ACP
 
-**Temporal Agentic ACP** provides production-ready agent development with **durable execution**, **fault tolerance**, and **automatic state management**. Instead of implementing ACP handlers directly, you implement Temporal workflows that are automatically integrated with the ACP protocol.
+**Temporal Async ACP** provides production-ready agent development with **durable execution**, **fault tolerance**, and **automatic state management**. Instead of implementing ACP handlers directly, you implement Temporal workflows that are automatically integrated with the ACP protocol.
 
 ## When to Use
 
@@ -26,11 +26,11 @@
 
 ### Not Ideal For:
 
-❌ **Learning Agentex basics** - Start with Base Agentic ACP
+❌ **Learning Agentex basics** - Start with Base Async ACP
 ❌ **Simple prototypes** - Higher complexity overhead
 ❌ **Development without Temporal** - Requires Temporal infrastructure
 
-## Key Differences from Base Agentic ACP
+## Key Differences from Base Async ACP
 
 ### No Manual ACP Handlers
 
@@ -110,7 +110,7 @@ from agentex.lib.types.fastacp import TemporalACPConfig
 
 # Create the ACP server
 acp = FastACP.create(
-    acp_type="agentic",
+    acp_type="async",
     config=TemporalACPConfig(
         type="temporal",
         temporal_address=os.getenv("TEMPORAL_ADDRESS", "localhost:7233")
@@ -320,7 +320,7 @@ if __name__ == "__main__":
 
 ## Next Steps
 
-- **Getting started?** Learn about [Base Agentic ACP](base.md) first
+- **Getting started?** Learn about [Base Async ACP](base.md) first
 - **Need to migrate?** Check the [Migration Guide](../../concepts/migration_guide.md)
 - **New to Agentex?** Follow the [Quick Start Guide on GitHub](https://github.com/scaleapi/scale-agentex#quick-start)
 - **Ready to build?** Check out [Temporal Tutorials on GitHub](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_agentic/100_temporal)

agentex/docs/docs/acp/best-practices.md

@@ -14,7 +14,7 @@ Guidelines for building robust, maintainable, and secure agents with ACP.
 
 - **Async operations** - Use `await` for all ADK operations
 - **Efficient state access** - Batch state operations when possible
-- **Resource cleanup** - Always clean up resources in Agentic ACP
+- **Resource cleanup** - Always clean up resources in Async ACP
 - **Caching** - Cache expensive operations when appropriate
 
 ## Security

agentex/docs/docs/acp/overview.md

@@ -19,7 +19,7 @@ Think of ACP as the "language" that agents and clients use to understand each ot
 
 Agentex supports two distinct ACP types, each designed for different use cases:
 
-| Feature | Sync ACP | Agentic ACP |
+| Feature | Sync ACP | Async ACP |
 |---------|----------|-------------|
 | **Best for** | Chat bots, simple Q&A | Complex workflows, stateful apps |
 | **Handlers** | 1 method (`on_message_send`) | 3 methods (`on_task_create`, `on_task_event_send`, `on_task_cancel`) |
@@ -37,7 +37,7 @@ Agentex supports two distinct ACP types, each designed for different use cases:
 - ✅ Quick responses - Fast, lightweight operations
 - ✅ Chat-like interfaces - Traditional conversational AI
 
-**Use Agentic ACP when:**
+**Use Async ACP when:**
 
 - ✅ Complex workflows - Multi-step processes with state
 - ✅ Persistent memory - Need to remember context across interactions
@@ -55,17 +55,17 @@ Perfect for simple chat bots and Q&A agents. Get started with the easiest approa
 
 **[→ Read Sync ACP Guide](sync.md)**
 
-### Agentic ACP
+### Async ACP
 
 Powerful event-driven approach for complex agents. Choose between Base (learning/development) or Temporal (production).
 
-**[→ Read Agentic ACP Overview](agentic/overview.md)**
+**[→ Read Async ACP Overview](async/overview.md)**
 
 ---
 
 ## Additional Resources
 
-- **[Migration Guide](../concepts/migration_guide.md)** - Upgrade from Sync to Agentic, or Base to Temporal
+- **[Migration Guide](../concepts/migration_guide.md)** - Upgrade from Sync to Async, or Base to Temporal
 - **[Best Practices](best-practices.md)** - Guidelines for performance, security, and maintainability
 
 ---

agentex/docs/docs/acp/sync.md

@@ -91,7 +91,7 @@ The `@acp.on_message_send` handler receives:
 
 ### Not Ideal For:
 
-❌ **Multi-step workflows** - Use Agentic ACP
+❌ **Multi-step workflows** - Use Async ACP
 ❌ **Complex state management** - Limited state tracking
 ❌ **Resource coordination** - No initialization/cleanup hooks
 ❌ **Long-running processes** - Better suited for quick responses
@@ -101,13 +101,13 @@ The `@acp.on_message_send` handler receives:
 - **Keep handlers simple** - Sync ACP is for straightforward logic
 - **Handle errors gracefully** - Return error messages to users
 - **Use optional state sparingly** - For simple session data only
-- **Consider migration** - Switch to Agentic ACP as complexity grows
+- **Consider migration** - Switch to Async ACP as complexity grows
 
 ---
 
 ## Next Steps
 
-- **Need more complexity?** Learn about [Agentic ACP](agentic/overview.md)
+- **Need more complexity?** Learn about [Async ACP](agentic/overview.md)
 - **Ready to upgrade?** See the [Migration Guide](../concepts/migration_guide.md)
 - **New to Agentex?** Follow the [Quick Start Guide on GitHub](https://github.com/scaleapi/scale-agentex#quick-start)
 - **Ready to build?** Check out [Sync ACP Tutorials on GitHub](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync)

agentex/docs/docs/api/types.md

@@ -128,6 +128,6 @@ For practical usage examples and patterns, see:
 - [TaskMessage Concepts](../concepts/task_message.md) - Working with messages
 - [Streaming Concepts](../concepts/streaming.md) - Real-time message streaming
 - [State Concepts](../concepts/state.md) - Managing persistent state
-- [Agent-to-Client Protocol (ACP)](../acp/overview.md) - Sync and Agentic ACP handler parameters explained
+- [Agent-to-Client Protocol (ACP)](../acp/overview.md) - Sync and Async ACP handler parameters explained
 
 

agentex/docs/docs/concepts/agents.md

@@ -67,7 +67,7 @@ The way you implement agents depends on which ACP (Agent-to-Client Protocol) typ
 
 **Sync ACP** agents are the simplest form - just a single function that processes messages and returns responses.
 
-**Agentic ACP** agents have multiple handler functions that manage the complete interaction lifecycle.
+**Async ACP** agents have multiple handler functions that manage the complete interaction lifecycle.
 
 ## Agent Relationships
 
@@ -163,7 +163,7 @@ async def handle_message_send(params: SendMessageParams):
         content="Hello from the agent!"
     )
 
-# Agentic ACP - Create messages explicitly
+# Async ACP - Create messages explicitly
 @acp.on_task_event_send
 async def handle_event_send(params: SendEventParams):
     await adk.messages.create(

agentex/docs/docs/concepts/callouts/events_vs_messages.md

@@ -1,7 +1,7 @@
 # Events vs Messages
 
-!!! danger "Critical for Agentic ACP"
-    **Events and TaskMessages serve different purposes and are stored in separate database tables.** This distinction is fundamental to understanding how Agentic ACP works.
+!!! danger "Critical for Async ACP"
+    **Events and TaskMessages serve different purposes and are stored in separate database tables.** This distinction is fundamental to understanding how Async ACP works.
 
 ## The Core Distinction
 

agentex/docs/docs/concepts/callouts/overview.md

@@ -17,7 +17,7 @@ This section covers critical implementation details that require special attenti
 **Critical for LLM integrations** - The important distinction between Agentex TaskMessages and LLM-compatible message formats, and when conversion is needed.
 
 ### [Events vs Messages](events_vs_messages.md)
-**Critical for Agentic ACP** - Understanding that events are ephemeral notifications, not persistent objects like TaskMessages.
+**Critical for Async ACP** - Understanding that events are ephemeral notifications, not persistent objects like TaskMessages.
 
 ### [Task/Agent Scoped State](state_management.md)
 **Critical for multi-agent systems** - How state is scoped per (task_id, agent_id) and why this design enables parallel agent execution.

agentex/docs/docs/concepts/callouts/race_conditions.md

@@ -1,4 +1,4 @@
-# Race Conditions in Agentic ACP
+# Race Conditions in Async ACP
 
 !!! danger "Critical for Production Systems"
     **All agentic ACP types can experience race conditions that corrupt agent state and cause unpredictable behavior.** Temporal ACP handles these better through singleton workflows and message queuing, but understanding race conditions is crucial for all production systems.
@@ -9,7 +9,7 @@ In **all agentic ACP types**, multiple events can trigger concurrent processing,
 
 **Temporal ACP** handles this better because workflows are singleton instances with built-in message queuing, while **Base ACP** requires manual race condition handling.
 
-### ❌ What Happens with Race Conditions (All Agentic ACP)
+### ❌ What Happens with Race Conditions (All Async ACP)
 
 ```python
 # Any agentic ACP - Multiple events can trigger simultaneously
@@ -229,7 +229,7 @@ async def on_task_event_send(self, params):
 
 ### Using Agent Task Tracker Cursors for Safe Processing
 
-For Base Agentic ACP, you can use **Agent Task Tracker cursors** to coordinate processing and reduce race conditions:
+For Base Async ACP, you can use **Agent Task Tracker cursors** to coordinate processing and reduce race conditions:
 
 ```python
 @acp.on_task_event_send
@@ -320,7 +320,7 @@ async def cursor_batch_handler(params: SendEventParams):
 ```
 
 !!! warning "Not a Complete Solution"
-    Agent Task Tracker cursors **reduce** race conditions but don't eliminate them entirely. For complete race condition prevention, use **Temporal Agentic ACP** which provides guaranteed sequential processing.
+    Agent Task Tracker cursors **reduce** race conditions but don't eliminate them entirely. For complete race condition prevention, use **Temporal Async ACP** which provides guaranteed sequential processing.
 
 ## Common Race Condition Scenarios
 

agentex/docs/docs/concepts/callouts/streaming.md

@@ -30,21 +30,21 @@ async def handle_message_send(params: SendMessageParams) -> AsyncGenerator[TaskM
             )
 ```
 
-### Agentic ACP: Three Streaming Options
+### Async ACP: Three Streaming Options
 
 Becuase Agentic Agents are completely async, they do not yield nor return anything in their ACP handlers. Instead, they should call the appropriate ADK functions to stream updates to the client.
 
 **Pub/Sub Architecture:**
-Agentex uses a **pub/sub mechanism** in the server to handle Agentic ACP streaming. Clients subscribe to **server-side events (SSE)** from Agentex, which allows them to receive streaming publications from agents in real-time. When an agent streams content, it publishes updates through the ADK, and all subscribed clients receive these updates immediately.
+Agentex uses a **pub/sub mechanism** in the server to handle Async ACP streaming. Clients subscribe to **server-side events (SSE)** from Agentex, which allows them to receive streaming publications from agents in real-time. When an agent streams content, it publishes updates through the ADK, and all subscribed clients receive these updates immediately.
 
-The ADK provides two different streaming approaches for agents behind Agentic ACPs depending on your needs:
+The ADK provides two different streaming approaches for agents behind Async ACPs depending on your needs:
 
 ## 1. Auto Send (Recommended for Most Cases)
 
 **Agentex handles everything automatically:**
 
 ```python
-# Agentic ACP - Auto send handles all delta accumulation
+# Async ACP - Auto send handles all delta accumulation
 @acp.on_task_event_send
 async def handle_event_send(params: SendEventParams):
     # Echo user message
@@ -80,7 +80,7 @@ async def handle_event_send(params: SendEventParams):
 **You get full control but handle everything manually:**
 
 ```python
-# Agentic ACP - Non-auto send: YOU handle everything
+# Async ACP - Non-auto send: YOU handle everything
 @acp.on_task_event_send
 async def handle_event_send(params: SendEventParams):
     # YOU must create the streaming context manually