You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+13-15Lines changed: 13 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,9 +14,9 @@
14
14
> [!IMPORTANT]
15
15
> OpenAgentPack is in beta. Public APIs and the `agents.yaml` schema may change before `1.0`. See the [changelog](./CHANGELOG.md).
16
16
17
-
<palign="center">
18
-
<imgsrc="https://img.alicdn.com/imgextra/i3/O1CN01xWDp5P1EP90HOZx9q_!!6000000000343-2-tps-1254-1254.png"width="360"alt="OpenAgentPack: one agents.yaml for multiple managed-agent providers">
19
-
</p>
17
+
18
+
19
+
`agents.yaml → validate → plan → apply`: bring agents back into Git, review the pending changes, then update remote resources.
20
20
21
21
One `agents.yaml` defines an agent's environment, model, instructions, tools, skills, MCP servers, vaults, and credentials. Review every change in a PR, preview it with `plan`, and apply it when ready — instead of rebuilding the same agent through console clicks.
▶ [Watch the Playground demo: switch provider and run the same agent scenario](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
37
+
36
38
## Why now
37
39
38
40
Agents are moving from personal tools to enterprise digital workers. But the things that make an agent valuable — its prompts, skills, knowledge files, tools, and runtime configuration — still live mainly inside cloud-provider consoles.
@@ -45,6 +47,10 @@ OpenAgentPack puts a declarative control plane between the agent and the cloud p
45
47
46
48
The goal is to make an agent an enterprise-controlled, portable, and inheritable digital asset.
47
49
50
+
<palign="center">
51
+
<imgsrc="https://img.alicdn.com/imgextra/i3/O1CN01xWDp5P1EP90HOZx9q_!!6000000000343-2-tps-1254-1254.png"width="360"alt="OpenAgentPack: one agents.yaml for multiple managed-agent providers">
52
+
</p>
53
+
48
54
### Declaration and portability: the agent as a blueprint
49
55
50
56
Borrowing Docker's declarative idea, OpenAgentPack brings everything that determines what an agent is — model, instructions, tools, skills, environment, files, and credential references — into one `agents.yaml` blueprint. The blueprint can live in Git, pass through pull-request review, reproduce an agent, and move across providers.
@@ -68,18 +74,6 @@ The mechanics are a single `agents.yaml`, a `validate → plan → apply` workfl
68
74
-**Dependency-aware** — Environment → Skill → Agent are created in topological order; a failed dependency skips its dependents instead of leaving half-built state.
69
75
-**Drift recovery** — detects when remote config has drifted from your declaration and reconciles it. The YAML is always the single source of truth.
`agents playground` launches a local WebUI, fetches the matching `@openagentpack/playground` package on demand, and opens it in your browser. Use `--provider` to target `bailian`, `qoder`, `ark`, or `claude`.
80
-
81
-
[Watch the Playground demo video](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
Run `agents playground` to launch the local WebUI, and use `--provider` to target `bailian`, `qoder`, `ark`, or `claude`. You can switch providers on the same declaration, run real sessions, and observe tool calls and artifacts.
88
+
89
+
▶ [Watch the full Playground demo](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
Use a bring-your-own-cloud (BYOC) environment when an administrator has already provisioned a self-hosted Qoder environment and, optionally, a tunnel to private services. OpenCMA references those resources; it does not own their lifecycle.
4
+
5
+
## Prerequisites
6
+
7
+
Ask the environment administrator for:
8
+
9
+
- an environment ID, such as `env_00xxxx`;
10
+
- a tunnel ID, such as `tnl_00xxxx`, when the agent needs access to private services;
11
+
- the Qoder credentials needed to manage the agent and start sessions.
12
+
13
+
Do not commit real IDs, private hostnames, or credentials. Use environment variables for credentials and keep live deployment configurations outside the repository.
14
+
15
+
## Configure the external resources
16
+
17
+
Declare the provisioned environment with `environment_id` and `self_hosted`. Declare a tunnel by its existing ID, then reference both from the agent.
18
+
19
+
```yaml
20
+
version: "1"
21
+
22
+
providers:
23
+
qoder:
24
+
api_key: ${QODER_PAT}
25
+
26
+
defaults:
27
+
provider: qoder
28
+
29
+
environments:
30
+
byoc-environment:
31
+
environment_id: env_00xxxx
32
+
config:
33
+
type: self_hosted
34
+
35
+
tunnels:
36
+
internal-network:
37
+
tunnel_id: tnl_00xxxx
38
+
39
+
agents:
40
+
private-service-assistant:
41
+
model: qmodel_latest
42
+
instructions: You can use the configured private services.
43
+
environment: byoc-environment
44
+
tunnel: internal-network
45
+
tools:
46
+
builtin: [Bash, Read]
47
+
```
48
+
49
+
`tunnel` is supported only for Qoder BYOC sessions and deployments. Omit the entire `tunnels` section and the agent's `tunnel` field when no private-network tunnel is needed.
50
+
51
+
## Apply and run
52
+
53
+
Apply the configuration to provision or update managed resources such as the agent. The declared environment and tunnel are only recorded as references.
54
+
55
+
```bash
56
+
agents apply -f agents.yaml
57
+
agents session run "Check the private service status" --agent private-service-assistant -f agents.yaml
58
+
```
59
+
60
+
You can override the configured IDs for a one-off session without changing the YAML:
61
+
62
+
```bash
63
+
agents session run "Check the private service status" \
64
+
--agent private-service-assistant \
65
+
--environment-id env_00xxxx \
66
+
--tunnel-id tnl_00xxxx \
67
+
-f agents.yaml
68
+
```
69
+
70
+
## Lifecycle and cleanup
71
+
72
+
When `environment_id` is present, OpenCMA never creates, updates, or remotely deletes that environment. Tunnels are always references and are never managed by OpenCMA.
73
+
74
+
OpenCMA records external ownership in its local state, and the record is sticky:
75
+
76
+
- Remove the environment declaration entirely and run `agents apply` or `agents destroy`: only the local state record is removed; the administrator-managed environment remains intact.
77
+
- Remove only the `environment_id` line while keeping the environment block: `plan`/`apply` fail with an `plan.environment.ownership_transition` error. Silently converting the reference into a managed resource would let OpenCMA modify — and eventually delete — a remote environment it does not own. To take over management deliberately, release the reference first with `agents state rm environment.<name>` and adopt the remote with `agents state import`.
78
+
- Point `environment_id` at a different existing environment: the reference is re-recorded and any deployments using it are updated. If the environment was previously managed by OpenCMA under a different remote ID, `plan` warns that the old remote is no longer tracked.
79
+
80
+
Deleting an agent, session, vault, or other managed resource still follows its normal lifecycle. Use the provider's administrator tooling to modify or delete BYOC environments and tunnels.
81
+
82
+
## Deployments and tunnels
83
+
84
+
A deployment that references the BYOC environment runs in that environment, and changing the referenced `environment_id` value updates the deployment on the next `apply`. Qoder's deployment API currently rejects `tunnel_id`, however, so a declared (or agent-inherited) tunnel is not sent with the deployment: scheduled and triggered runs execute without the tunnel, and `validate`/`plan` emits a `qoder.deployment.tunnel.unsupported` warning. Use sessions for workloads that need private-network MCP access.
85
+
86
+
## Troubleshooting
87
+
88
+
| Symptom | Check |
89
+
|--------|-------|
90
+
| Session cannot reach a private service | Confirm the supplied tunnel ID is enabled for the environment and that the service hostname is reachable from the private network. |
91
+
| `Tunnel '...' is not defined in config` | Add the name under `tunnels`, or pass `--tunnel-id` for a one-off session. |
92
+
| Tunnel unsupported diagnostic | Ensure the agent or deployment targets Qoder; tunnels are not sent to other providers. |
93
+
| Environment cannot be resolved | Verify the administrator-provided `environment_id` and the agent's `environment` reference. |
94
+
| `plan.environment.ownership_transition` error | Restore `environment_id`, or release the reference with `agents state rm environment.<name>` before managing the environment with OpenCMA. |
95
+
| `qoder.deployment.tunnel.unsupported` warning | Expected: Qoder deployments cannot carry a tunnel today. Use sessions for private-network MCP access. |
96
+
97
+
For field definitions, see the [configuration reference](../reference/configuration.md).
| `environment_id` | string | no | Existing environment ID. When present, OpenCMA never creates, updates, or deletes the remote environment. Removing this line later is blocked as an ownership error — release first with `agents state rm` (see [Use BYOC environments](../guides/use-byoc-environments.md)). |
88
+
| `config.type` | `"cloud"` \| `"self_hosted"` | yes | Environment type. `self_hosted` is used for Qoder BYOC. |
| `metadata` | map<string,string> | no | Free-form metadata. |
91
95
96
+
## Tunnel (Qoder BYOC)
97
+
98
+
```yaml
99
+
tunnels:
100
+
internal-network:
101
+
tunnel_id: tnl_00xxxx
102
+
```
103
+
104
+
Tunnels are existing Qoder resources allocated by the BYOC administrator. They are passed only when a Qoder session/deployment is created and are never created, updated, or deleted by OpenCMA. See [Use BYOC environments](../guides/use-byoc-environments.md) for a complete setup and lifecycle guide.
105
+
92
106
## Vault
93
107
94
108
```yaml
@@ -166,6 +180,7 @@ agents:
166
180
model: <string> | { <provider>: <string> }
167
181
instructions: <string> | <path>
168
182
environment: <string>
183
+
tunnel: <string> # optional; Qoder BYOC tunnel name
tunnel: <string> # optional; Qoder BYOC only (see note below)
217
234
vaults: [ <string> ]
218
235
memory_stores: [ <string> ]
219
236
resources: [ DeploymentResource ]
@@ -226,6 +243,8 @@ deployments:
226
243
227
244
`initial_events`is a discriminated union; `schedule.expression` must be a 5-field cron expression.
228
245
246
+
> **Deployment `tunnel` caveat:** Qoder's deployment API does not accept `tunnel_id`, so the tunnel is dropped from the deployment payload and server-side runs execute without it (`validate`/`plan` emits a warning). Use sessions for private-network MCP access; see [Use BYOC environments](../guides/use-byoc-environments.md).
0 commit comments