Skip to content

Commit 16b257b

Browse files
volcano-sh-botvolcano-sh-bot
authored
Merge pull request #54 from acsoto/agentrun
Add Agentrun CLI
2 parents e3fd8fb + ecf3e19 commit 16b257b

23 files changed

+4174
-0
lines changed

‎cmd/cli/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Project specific
2+
agent_metadata.yaml
3+
Dockerfile

‎cmd/cli/README.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
# AgentCube CLI
2+
3+
AgentCube CLI is a developer tool that streamlines the development, packaging, building, and deployment of AI agents to AgentCube. It provides a unified interface for managing the complete agent lifecycle from local development to cloud deployment.
4+
5+
## Quick Start
6+
7+
### Prerequisites
8+
9+
- Python 3.8+
10+
- Git
11+
- Docker (optional, for container builds)
12+
13+
### Installation
14+
15+
```bash
16+
# Clone the repository
17+
git clone https://github.com/volcano-sh/agentcube.git
18+
cd agentcube/cmd/cli
19+
20+
# Create virtual environment
21+
python3 -m venv venv
22+
source venv/bin/activate # On Windows: venv\Scripts\activate
23+
24+
# Install in development mode
25+
pip install -e .
26+
```
27+
28+
### Your First Agent
29+
30+
1. **Package an existing agent:**
31+
```bash
32+
kubectl agentcube pack -f examples/hello-agent --agent-name "my-agent"
33+
```
34+
35+
2. **Build the container image:**
36+
```bash
37+
kubectl agentcube build -f examples/hello-agent
38+
```
39+
40+
3. **Publish to AgentCube:**
41+
```bash
42+
kubectl agentcube publish \
43+
-f examples/hello-agent \
44+
--image-url "docker.io/username/my-agent" \
45+
```
46+
47+
4. **Invoke your agent:**
48+
```bash
49+
kubectl agentcube invoke -f examples/hello-agent --payload '{"prompt": "Hello World!"}'
50+
```
51+
52+
5. **Check status:**
53+
```bash
54+
kubectl agentcube status -f examples/hello-agent
55+
```
56+
57+
## Features
58+
59+
- **Multi-language Support**: Python, Java (with more languages planned)
60+
- **Flexible Build Modes**: Local Docker builds and cloud builds
61+
- **Multi-Provider Deployment**: Support for AgentCube CRDs and standard Kubernetes deployments
62+
- **AgentCube Integration**: Seamless publishing and management
63+
- **Developer-friendly**: Rich CLI experience with detailed feedback
64+
- **CI/CD Ready**: Python SDK for programmatic access
65+
- **Extensible Architecture**: Plugin system for custom providers
66+
67+
## Installation
68+
69+
### From PyPI (Recommended)
70+
71+
```bash
72+
pip install agentcube
73+
```
74+
75+
### From Source
76+
77+
```bash
78+
git clone https://github.com/volcano-sh/agentcube.git
79+
cd agentcube/cmd/cli
80+
pip install -e .
81+
```
82+
83+
## Documentation
84+
85+
- [Design](AgentCube-CLI-Design.md)
86+
- [Examples](examples/)
87+
88+
## Configuration
89+
90+
AgentCube uses a `agent_metadata.yaml` file to configure your agent:
91+
92+
```yaml
93+
agent_name: my-agent
94+
description: "A sample AI agent"
95+
language: python
96+
entrypoint: python main.py
97+
port: 8080
98+
build_mode: local
99+
requirements_file: requirements.txt
100+
```
101+
102+
## Architecture
103+
104+
AgentCube CLI follows a modular four-layer architecture:
105+
106+
1. **CLI Layer**: Typer-based command interface
107+
2. **Runtime Layer**: Business logic and Python SDK
108+
3. **Operations Layer**: Core domain logic
109+
4. **Services Layer**: External integrations
110+
111+
## Deployment Providers
112+
113+
AgentCube supports two deployment providers:
114+
115+
### AgentCube Provider (Default)
116+
117+
Deploys agents using AgentCube's custom AgentRuntime CRDs, providing enhanced agent lifecycle management and integration with the AgentCube ecosystem.
118+
119+
```bash
120+
kubectl agentcube publish -f examples/hello-agent --provider agentcube
121+
```
122+
123+
### Standard Kubernetes Provider
124+
125+
Deploys agents as standard Kubernetes Deployments and Services, suitable for environments without AgentCube CRDs installed.
126+
127+
```bash
128+
kubectl agentcube publish -f examples/hello-agent --provider k8s \
129+
--node-port 30080 \
130+
--replicas 3
131+
```
132+
133+
## Command Reference
134+
135+
### `kubectl agentcube pack`
136+
Package the agent application into a standardized workspace.
137+
138+
```bash
139+
kubectl agentcube pack [OPTIONS]
140+
141+
Options:
142+
-f, --workspace TEXT Path to the agent workspace directory [default: .]
143+
--agent-name TEXT Override the agent name
144+
--language TEXT Programming language (python, java)
145+
--entrypoint TEXT Override the entrypoint command
146+
--port INTEGER Port to expose in the Dockerfile
147+
--build-mode TEXT Build strategy: local or cloud
148+
--description TEXT Agent description
149+
--output TEXT Output path for packaged workspace
150+
--verbose Enable detailed logging
151+
```
152+
153+
### `kubectl agentcube build`
154+
Build the agent image based on the packaged workspace.
155+
156+
```bash
157+
kubectl agentcube build [OPTIONS]
158+
159+
Options:
160+
-f, --workspace TEXT Path to the agent workspace directory [default: .]
161+
-p, --proxy TEXT Custom proxy URL for dependency resolution
162+
--cloud-provider TEXT Cloud provider name (e.g., huawei)
163+
--output TEXT Output path for build artifacts
164+
--verbose Enable detailed logging
165+
```
166+
167+
### `kubectl agentcube publish`
168+
Publish the agent to AgentCube
169+
170+
```bash
171+
kubectl agentcube publish [OPTIONS]
172+
173+
Options:
174+
-f, --workspace TEXT Path to the agent workspace directory [default: .]
175+
--version TEXT Semantic version string (e.g., v1.0.0)
176+
--image-url TEXT Image repository URL (required in local build mode)
177+
--image-username TEXT Username for image repository
178+
--image-password TEXT Password for image repository
179+
--description TEXT Agent description
180+
--region TEXT Deployment region
181+
--cloud-provider TEXT Cloud provider name (e.g., huawei)
182+
--provider TEXT Target provider for deployment (agentcube, k8s). 'agentcube' deploys AgentRuntime CR, 'k8s' deploys standard K8s Deployment/Service. [default: agentcube]
183+
--node-port INTEGER Specific NodePort to use (30000-32767) for K8s deployment
184+
--replicas INTEGER Number of replicas for K8s deployment (default: 1)
185+
--endpoint TEXT Custom API endpoint for AgentCube or Kubernetes cluster
186+
--namespace TEXT Kubernetes namespace to use for deployment [default: default]
187+
--verbose Enable detailed logging
188+
```
189+
190+
### `kubectl agentcube invoke`
191+
Invoke a published agent via AgentCube or Kubernetes.
192+
193+
```bash
194+
kubectl agentcube invoke [OPTIONS]
195+
196+
Options:
197+
-f, --workspace TEXT Path to the agent workspace directory [default: .]
198+
--payload TEXT JSON-formatted input passed to the agent [default: {}]
199+
--header TEXT Custom HTTP headers (e.g., 'Authorization: Bearer token')
200+
--provider TEXT Target provider for deployment (agentcube, k8s). 'agentcube' deploys AgentRuntime CR, 'k8s' deploys standard K8s Deployment/Service. [default: agentcube]
201+
--verbose Enable detailed logging
202+
```
203+
204+
### `kubectl agentcube status`
205+
Check the status of a published agent.
206+
207+
```bash
208+
kubectl agentcube status [OPTIONS]
209+
210+
Options:
211+
-f, --workspace TEXT Path to the agent workspace directory [default: .]
212+
--provider TEXT Target provider for deployment (agentcube, k8s). 'agentcube' deploys AgentRuntime CR, 'k8s' deploys standard K8s Deployment/Service. [default: agentcube]
213+
--verbose Enable detailed logging
214+
```
215+
216+
## Agent Structure
217+
218+
An AgentCube workspace typically contains:
219+
220+
```
221+
my-agent/
222+
├── agent_metadata.yaml # Agent configuration (auto-generated)
223+
├── Dockerfile # Container definition (auto-generated)
224+
├── requirements.txt # Python dependencies
225+
├── main.py # Agent entrypoint
226+
└── src/ # Source code
227+
```
228+
229+
### `agent_metadata.yaml`
230+
231+
```yaml
232+
agent_name: my-agent
233+
description: "My AI agent"
234+
language: python
235+
entrypoint: python main.py
236+
port: 8080
237+
build_mode: local
238+
requirements_file: requirements.txt
239+
```
240+
241+
## Language Support
242+
243+
### Python
244+
245+
Fully supported with automatic dependency management and Dockerfile generation.
246+
247+
- Supported versions: Python 3.8+
248+
- Package manager: pip
249+
- Dependencies file: requirements.txt
250+
- Example: [examples/hello-agent](examples/hello-agent)
251+
252+
### Java
253+
254+
Supported with Maven-based builds and OpenJDK runtime.
255+
256+
- Supported versions: Java 17+
257+
- Build tool: Maven
258+
- Dependencies file: pom.xml
259+
- Note: Java example coming soon
260+
261+
## Troubleshooting
262+
263+
### Common Issues
264+
265+
1. **"Docker is not available"**
266+
- Install Docker and make sure it's running
267+
- Use `--build-mode cloud` for cloud builds
268+
269+
2. **"Metadata file not found"**
270+
- Run `kubectl agentcube pack` first to generate metadata
271+
- Ensure you're in the correct workspace directory
272+
273+
3. **"Agent not published yet"**
274+
- Run `kubectl agentcube publish` before trying to invoke
275+
- Check that the build completed successfully
276+
277+
4. **"Provider not found"**
278+
- Ensure you're using a valid provider: `agentcube` or `k8s`
279+
- Check that your Kubernetes cluster has the required CRDs (for agentcube provider)
280+
281+
### Getting Help
282+
283+
```bash
284+
# General help
285+
kubectl agentcube --help
286+
287+
# Command-specific help
288+
kubectl agentcube pack --help
289+
kubectl agentcube build --help
290+
kubectl agentcube publish --help
291+
kubectl agentcube invoke --help
292+
kubectl agentcube status --help
293+
```
294+
295+
## License
296+
297+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
298+
299+
## Links
300+
301+
- [AgentCube Main Project](https://github.com/volcano-sh/agentcube)
302+
- [Volcano Scheduler](https://github.com/volcano-sh/volcano)
303+
- [Issue Tracker](https://github.com/volcano-sh/agentcube/issues)

‎cmd/cli/agentcube/__init__.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
"""
2+
AgentCube CLI - A developer tool for packaging, building, and deploying AI agents to AgentCube.
3+
"""
4+
5+
__version__ = "0.1.0"
6+
__author__ = "AgentCube Community"
7+
__email__ = "agentcube@volcano.sh"
8+
9+
from .cli.main import app
10+
from .runtime.pack_runtime import PackRuntime
11+
from .runtime.build_runtime import BuildRuntime
12+
from .runtime.publish_runtime import PublishRuntime
13+
from .runtime.invoke_runtime import InvokeRuntime
14+
15+
__all__ = [
16+
"app",
17+
"PackRuntime",
18+
"BuildRuntime",
19+
"PublishRuntime",
20+
"InvokeRuntime",
21+
]

‎cmd/cli/agentcube/cli/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""
2+
CLI module for AgentCube.
3+
"""

0 commit comments

Comments
 (0)