---
name: grix-egg
description: "Program-driven hatching: AI only organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting. Use for creating or installing an Agent from an egg package, including collecting and professionally organizing its name and behavioral introduction before remote creation."
---

# Grix Egg

`grix-egg` follows a "program-first, AI-assists" approach.
AI no longer manually relays create/bind/accept.

## 1. AI Role Boundary

You only do three things:

1. Organize user input into standard parameters
2. Call `grix_egg`
3. Report results / request supplementary parameters based on the returned JSON

Do not manually execute these actions:

1. Remote agent creation
2. Local bind
3. Gateway operations
4. Test group acceptance

## 2. Agent Profile Intake

Before calling `grix_egg` with `route=create_new`:

1. Ensure the request has both a concrete Agent name and a usable introduction.
2. If either one is missing or too vague, pause and ask one concise question: “这个 Agent 主要做什么？核心职责、服务对象和工作边界是什么？” Do not start hatching yet.
3. Turn the user's answer into a concise professional `agentName` and a professional `introduction`. The introduction must describe purpose, core responsibilities, intended users or scenarios, operating expectations, and important boundaries.
4. Preserve the user's facts and intent; do not invent permissions, authority, expertise, or responsibilities.
5. Treat the introduction as the Agent's behavioral specification. Pass it through the actual `introduction` parameter so the program sends it in `grix_admin action=create_agent`; do not leave it only in chat, `soulContent`, or persona files.
6. When using a raw `installContext` that lacks the finalized profile, pass `agentName` and `introduction` alongside it as explicit overrides.

## 3. Standard Call Entry

Prefer passing the raw install card:

```json
{ "installContext": "<raw json>" }
```

If there is no install card, pass structured parameters:

1. `route`: `create_new` | `existing` | `existing_claude`
2. `agentName` (required for `create_new`)
3. `introduction` (required for `create_new`; professionally organized according to **Agent Profile Intake**)
4. `agentIdSlug` or `localAgentName`
5. `downloadUrl`
6. `existingCredentials` (required for `existing`)
7. Optional: `packageHash`, `soulContent`, `soulFile`, `categoryId`, `categoryName`, `isMain`, `expectedSubstring`, `statusTarget`, `resume`, `installId`

## 4. Route Behavior

1. `create_new`: program automatically completes creation, installation, binding, acceptance, and status reporting
2. `existing`: program automatically completes existing credential installation and acceptance
3. `existing_claude`: program returns `unsupported_route`, handled by a standalone Claude installer

## 5. Acceptance Rules

Program has fixed acceptance logic:

1. Test group members must include: main agent, trigger user, target agent
2. Probe uses `@<target_agent_id>` mention
3. Only the first non-empty reply after the probe from the target agent is accepted
4. `expectedSubstring` is only an optional enhancement condition

## 6. Result Reporting

When `ok=true`:

1. Report `install_id`, `route`, target agent, acceptance result
2. If `acceptance.reply_content` and `testGroup` are present, include them for the user
3. If `interaction_status=degraded`, explain that the main flow succeeded but status reporting partially failed

When `ok=false`:

1. Use `reason` and `suggestion` directly to explain the failure
2. Only supplement external inputs that the program explicitly identifies as missing
3. Use `resume=true` + `installId` when continuation is needed

## 7. Prohibited Actions

1. Do not use `curl`/`fetch`/`axios` to directly connect to `/v1/agent-api`
2. Do not manually modify `openclaw.json`
3. Remote actions must only go through typed tools: `grix_admin`, `grix_group`, `grix_query`
4. Do not claim installation success before acceptance is complete

## References

1. [references/api-contract.md](references/api-contract.md)
