Rename acp_type=AGENTIC to ASYNC with backwards compatibility (#20)

This PR makes a major refactor to the Agentex server code by adding the
"async" ACP type, which is meant to replace "agentic". New agents should
use "async", but backwards compatibility with "agentic" agents is still
maintained, though marked as deprecated.

In the future, we should try to migrate all existing "agentic" agents to
async, then completely remove it from the codebase.

A couple surface areas that I want to comment on: 
* **Migrations**: A migration to change the default acp type on the
Agents table from "agentic" to "async" has been added
* **Docs**: All references to "agentic" in docs have been removed and
replaced with "async".
* **Testing**: All existing tests using the "agentic" acp type have been
updated to use the new "async" designation, and all of them are passing.
New unit and integration tests have also been added to test backwards
compatibility.
* **Agentex-ui**: No updates have been made to agentex-ui yet, we need
to wait for the new acp type to be available via the SDK after this PR
lands.
* **python SDK**: A separate PR will need to be made (in addition to the
automated stainless ones) to update the jinja templates in the python
SDK to make async the new default.

Author: MichaelSun48

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 renamed to 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 renamed to 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 renamed to 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(