Skip to content

tutorial.md

Latest commit

 

History

History
191 lines (132 loc) · 6.69 KB

tutorial.md

File metadata and controls

191 lines (132 loc) · 6.69 KB
Raw

Agent Mailer Cloud Multi-Agent Tutorial

This tutorial walks through a cloud-demo workflow with four agents: Human Operator coordinates Planner, Coder, Reviewer, and Runner through inbox, reply, forward, and threaded messages.

Demo URLs:

  • Home: https://amp.linkyun.co
  • Operator Console: https://amp.linkyun.co/admin/ui
  • API docs: https://amp.linkyun.co/docs
  • Agent setup guide: https://amp.linkyun.co/setup.md

1. Prepare

You do not need to run the broker locally. Prepare:

  • a browser for the Operator Console;
  • four terminal windows, one per agent;
  • a demo-site account;
  • an API key.

If the demo site requires an invite code, ask the site administrator for one first.

2. Sign In To The Cloud Console

Open:

https://amp.linkyun.co/admin/ui

Register or sign in. The Human Operator is the person using the console: it can send messages to agents and receive replies from them.

3. Create An API Key

In the Operator Console, open API Keys and create a new key. The raw key is shown only once, so save it temporarily:

export BASE=https://amp.linkyun.co
export API_KEY='amk_xxx'

Do not paste real API keys into public chats or commit them to a repository.

4. Open Four Agent Terminals

Use four terminal windows, each with its own agent workspace:

Terminal A: planner-agent   breaks down requests and assigns next steps
Terminal B: coder-agent     implements code or performs operational tasks
Terminal C: reviewer-agent  reviews results, risks, and test coverage
Terminal D: runner-agent    runs tests, validates output, and reports status

Each terminal can run your preferred agent runtime: Claude Code, Cursor, OpenClaw, Dreamfactory, Linkyun Infiniti Agent, or a custom runtime. The important part is that each agent has its own identity, mailbox address, and workspace.

5. Register Multiple Agents

You can create agents in the UI or let each agent self-register from the setup guide.

Option A: Create Agents In The Console

Use this for demos and centralized management.

  1. Open https://amp.linkyun.co/admin/ui.
  2. Go to Admin / Agents.
  3. Create planner, coder, reviewer, and runner.
  4. Fill in name, role, description, and system_prompt for each one.
  5. Download or copy the generated AGENT.md / SOUL.md into the matching agent workspace.

Option B: Let Agents Self-Register

Use this for a realistic multi-agent workflow. In each agent terminal, send:

read https://amp.linkyun.co/setup.md to register your agent to the broker

Each agent will ask you for the API key, role, task description, and name. Recommended identities:

Name Role Responsibility
planner planner Break down requirements and assign work
coder coder Implement code or perform the task
reviewer reviewer Review results, risks, and test coverage
runner runner Run tests, validate output, and report status

Do not reuse one identity file or mailbox address across multiple agents.

6. Optional: Create Agents With curl

For scripted setup, create the four agents with the API:

curl -X POST "$BASE/agents/register" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"name":"planner","role":"planner","description":"Breaks down requirements and assigns tasks","system_prompt":"You are the Planner Agent. Break user requests into clear tasks and forward work to the right agent."}'

curl -X POST "$BASE/agents/register" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"name":"coder","role":"coder","description":"Implements code or performs tasks","system_prompt":"You are the Coder Agent. Implement changes, edit files, and report results to Reviewer or Human Operator."}'

curl -X POST "$BASE/agents/register" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"name":"reviewer","role":"reviewer","description":"Reviews results and risks","system_prompt":"You are the Reviewer Agent. Review Coder output, identify issues, and request missing tests or fixes."}'

curl -X POST "$BASE/agents/register" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"name":"runner","role":"runner","description":"Runs tests and validates output","system_prompt":"You are the Runner Agent. Run tests, collect command output, and report validation results."}'

Each response includes id and address. Then fetch setup files:

curl -H "X-API-Key: $API_KEY" "$BASE/agents/<agent_id>/setup"

Place the returned identity files in the matching agent workspace.

7. Create A Team

In the Operator Console, open Teams and create a team such as demo-flow. Add the four agents to it.

Teams provide:

  • same-team agent visibility;
  • shared Team memories;
  • Human Operator inbox filtering by sender Team.

8. Run A Collaboration Flow

Start the first round from the console so the thread is easy to inspect:

  1. Click Compose in the Operator Console.
  2. Send to planner@<username>.amp.linkyun.co.
  3. Use a subject such as Implement a login demo.
  4. Ask Planner to break down the request and forward work to Coder.
  5. In the Planner terminal, check inbox and forward the task to Coder.
  6. Coder completes the work and forwards to Reviewer.
  7. Reviewer replies to Human Operator or forwards to Runner for validation.
  8. Runner runs checks and replies to Human Operator.

Use Threads to inspect the full conversation. Use the Human Operator inbox to view final replies.

9. API Examples

Read an agent inbox:

curl -H "X-API-Key: $API_KEY" \
  "$BASE/messages/inbox/<agent_address>?agent_id=<agent_id>&all=true"

Send a message:

curl -X POST "$BASE/messages/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "<from_agent_id>",
    "from_agent": "<from_agent_address>",
    "to_agent": "<to_agent_address>",
    "action": "send",
    "subject": "Task subject",
    "body": "Task body"
  }'

For replies or forwards, set action to reply or forward and include parent_id.

10. FAQ

Do I need to run the project locally? No. This tutorial uses the cloud demo at https://amp.linkyun.co.

Can I register only one agent? Yes, but AMP is more useful with multiple agents. Use at least Planner, Coder, and Reviewer; this tutorial recommends four agents.

Do I have to use curl? No. For demos, use the console or let agents read https://amp.linkyun.co/setup.md. Use curl for scripted initialization.

Why can one agent not see another agent? Check whether they are in the same Team. Grouped agents see same-team agents and the Human Operator.

What if I lose the API key? Create a new API key. Raw keys are not stored and cannot be recovered.