|
1 | | -# hello-sync - AgentEx Starter Template |
| 1 | +# [Sync] Hello ACP |
2 | 2 |
|
3 | | -This is a generic starter template for building agents with the AgentEx framework. It provides a basic implementation of the Agent 2 Client Protocol (ACP) to help you get started quickly. |
| 3 | +This is a simple AgentEx agent that just says hello and acknowledges the user's message to show which ACP methods need to be implemented for the sync ACP type. |
4 | 4 |
|
5 | | -## What You'll Learn |
6 | | - |
7 | | -- **Tasks**: A task is a grouping mechanism for related messages. Think of it as a conversation thread or a session. |
8 | | -- **Messages**: Messages are communication objects within a task. They can contain text, data, or instructions. |
9 | | -- **ACP Events**: The agent responds to four main events: |
10 | | - - `task_received`: When a new task is created |
11 | | - - `task_message_received`: When a message is sent within a task |
12 | | - - `task_approved`: When a task is approved |
13 | | - - `task_canceled`: When a task is canceled |
14 | | - |
15 | | -## Running the Agent |
16 | | - |
17 | | -1. Run the agent locally: |
18 | | -```bash |
19 | | -agentex agents run --manifest manifest.yaml |
20 | | -``` |
21 | | - |
22 | | -The agent will start on port 8000 and print messages whenever it receives any of the ACP events. |
23 | | - |
24 | | -## What's Inside |
25 | | - |
26 | | -This template: |
27 | | -- Sets up a basic ACP server |
28 | | -- Handles each of the required ACP events with simple print statements |
29 | | -- Provides a foundation for building more complex agents |
30 | | - |
31 | | -## Next Steps |
32 | | - |
33 | | -For more advanced agent development, check out the AgentEx tutorials: |
34 | | - |
35 | | -- **Tutorials 00-08**: Learn about building synchronous agents with ACP |
36 | | -- **Tutorials 09-10**: Learn how to use Temporal to power asynchronous agents |
37 | | - - Tutorial 09: Basic Temporal workflow setup |
38 | | - - Tutorial 10: Advanced Temporal patterns and best practices |
39 | | - |
40 | | -These tutorials will help you understand: |
41 | | -- How to handle long-running tasks |
42 | | -- Implementing state machines |
43 | | -- Managing complex workflows |
44 | | -- Best practices for async agent development |
45 | | - |
46 | | -## The Manifest File |
47 | | - |
48 | | -The `manifest.yaml` file is your agent's configuration file. It defines: |
49 | | -- How your agent should be built and packaged |
50 | | -- What files are included in your agent's Docker image |
51 | | -- Your agent's name and description |
52 | | -- Local development settings (like the port your agent runs on) |
53 | | - |
54 | | -This file is essential for both local development and deployment of your agent. |
55 | | - |
56 | | -## Project Structure |
57 | | - |
58 | | -``` |
59 | | -hello_sync/ |
60 | | -├── project/ # Your agent's code |
61 | | -│ ├── __init__.py |
62 | | -│ └── acp.py # ACP server and event handlers |
63 | | -├── Dockerfile # Container definition |
64 | | -├── manifest.yaml # Deployment config |
65 | | -└── requirements.txt # Dependencies |
66 | | -``` |
67 | | - |
68 | | -## Development |
69 | | - |
70 | | -1. **Customize Event Handlers** |
71 | | - - Modify the handlers in `acp.py` to implement your agent's logic |
72 | | - - Add your own tools and capabilities |
73 | | - - Implement custom state management |
74 | | - |
75 | | -2. **Add Dependencies** |
76 | | - - Add required packages to `requirements.txt` |
77 | | - - Update the manifest with any needed credentials |
78 | | - |
79 | | -## Local Development |
80 | | - |
81 | | -1. **Install AgentEx** |
82 | | -```bash |
83 | | -cd agentex-py |
84 | | -uv venv |
85 | | -source .venv/bin/activate |
86 | | -uv sync |
87 | | -``` |
88 | | - |
89 | | -2. **Deploy your agent** |
90 | | -```bash |
91 | | -# From this directory |
92 | | -export ENVIRONMENT=development && agentex agents create --manifest manifest.yaml |
93 | | -``` |
94 | | - |
95 | | -4. **Interact with your agent** |
96 | | - |
97 | | -Option 0: CLI (deprecated - to be replaced once a new CLI is implemented - please use the web UI for now!) |
98 | | -```bash |
99 | | -# Submit a task via CLI |
100 | | -agentex tasks submit --agent {{ agent_name }} --task "Your task here" |
101 | | -``` |
102 | | - |
103 | | -Option 1: Web UI |
104 | | -```bash |
105 | | -# Start the local web interface |
106 | | -cd agentex-web |
107 | | -make dev |
108 | | - |
109 | | -# Then open http://localhost:3000 in your browser to chat with your agent |
110 | | -``` |
111 | | - |
112 | | -## Development Tips |
113 | | - |
114 | | -1. **Local Testing** |
115 | | -- Set environment variables in project/.env for any required credentials. OR you can set these in the manifest.yaml |
116 | | - |
117 | | -### To build the agent Docker image locally (normally not necessary): |
118 | | - |
119 | | -1. First, set up CodeArtifact authentication: |
120 | | -```bash |
121 | | -../../setup-build-codeartifact.sh |
122 | | -``` |
123 | | - |
124 | | -2. Build the agent image: |
125 | | -```bash |
126 | | -agentex agents build --manifest manifest.yaml --secret 'id=codeartifact-pip-conf,src=.codeartifact-pip-conf' |
127 | | -``` |
| 5 | +## Official Documentation |
128 | 6 |
|
| 7 | +[000 Hello ACP](https://dev.agentex.scale.com/docs/tutorials/sync/000_hello_acp) |
0 commit comments