Agent API Documentation

本文档介绍如何使用 Agent API 创建、管理和与 AI Agent 对话。

Base URL

所有端点都以 /agents 为前缀。

Authentication（身份验证）

身份验证通过 API Key 完成。

Header：

x-api-key: <your_api_key>

Quick Start: Build an Agent in 60 Seconds（快速开始：60 秒创建 Agent）

最快的入门方式是使用 Quick Create 端点。它允许你从一个高层目标出发，一步创建出完整可用的 Agent。

Step 1: Create your Agent（创建 Agent）

将目标发送到 /quick-create 端点。

Request Body：

{
  "prompt": "I want an agent that specializes in creating minimalist streetware brand assets and social media content."
}

Response (200 OK)：

{
  "id": "agent_abc123",
  "name": "Streetware Guru",
  "system_prompt": "You are an expert brand designer...",
  "skills": [...]
}

Step 2: Start Chatting（开始对话）

使用响应中的 id 开始对话。要在多条消息之间保留记忆，必须提供一致的 conversation_id（任意有效 UUID）。

Request Body：

{
  "message": "Hey! Let's start by designing a simple logo for a brand called 'Vapor'.",
  "conversation_id": "my-session-123"
}

[!IMPORTANT] 如果省略 conversation_id，Agent 会把每条消息视为全新的交互，不会记住之前的决定。

Detailed API Reference（API 详细参考）

以下端点可以更细粒度地控制 Agent 的生命周期。

1. Suggest Agent Configuration (Architect)（建议 Agent 配置）

根据高层目标生成推荐的 Agent 配置（角色设定 + 技能）。

Request Body：

{
  "prompt": "I want an agent that can help me write python code and debug errors."
}

Response (200 OK)：

{
  "name": "Python Wizard",
  "description": "An expert Python developer focused on writing clean, efficient code.",
  "system_prompt": "You are an expert Python developer...",
  "recommended_skill_ids": ["python_exec", "file_io"]
}

2. List Skills（列出技能）

列出可以分配给 Agent 的所有可用技能。

Response (200 OK)：

[
  {
    "id": "web_search",
    "aitask_id": 101,
    "name": "Web Search",
    "description": "Search the internet for information."
  },
  {
    "id": "code_exec",
    "aitask_id": 102,
    "name": "Code Execution",
    "description": "Execute python code."
  }
]

3. Create Agent（创建 Agent）

创建一个新的专用 Agent。

Request Body：

{
  "name": "Research Assistant",
  "description": "Helps gather information.",
  "system_prompt": "You are a helpful research assistant.",
  "skill_ids": ["web_search", "summarization"]
}

字段：

  • name（string，必填）：Agent 名称。
  • description（string，可选）：简短描述。
  • system_prompt（string，必填）：Agent 的核心指令。
  • skill_ids（字符串数组）：要附加的技能 ID 列表。

Response (200 OK)：

{
  "id": "agent_12345",
  "name": "Research Assistant",
  "description": "Helps gather information.",
  "system_prompt": "You are a helpful research assistant.",
  "icon_url": null,
  "daily_credit_limit": 100.0,
  "created_at": "2024-01-01T12:00:00Z",
  "skills": [
    {
        "id": "web_search",
        "name": "Web Search",
        ...
    }
  ]
}

4. List User Agents（列出用户 Agent）

获取当前已验证用户创建的所有 Agent。

Response (200 OK)：

[
  {
    "id": "agent_12345",
    "name": "Research Assistant",
    ...
  },
  {
    "id": "agent_67890",
    "name": "Coding Bot",
    ...
  }
]

5. Get Agent Details（获取 Agent 详情）

按 ID 获取指定 Agent 的详情。

Response (200 OK)：

返回 AgentResponse 对象（与 Create Agent 的响应相同）。

Response (404 Not Found)：

{
  "detail": "Agent not found"
}

6. Update Agent（更新 Agent）

编辑已有 Agent。只有所有者可以更新。

Request Body：

{
  "name": "Advanced Research Assistant",
  "description": "Updated description.",
  "system_prompt": "You are an advanced researcher...",
  "icon_url": "https://example.com/icon.png",
  "skill_ids": ["web_search", "data_analysis"]
}

注意：所有字段都是可选的，只会更新实际提供的字段。

Response (200 OK)：

返回更新后的 AgentResponse 对象。

7. Delete Agent（删除 Agent）

删除 Agent。只有所有者可以删除。

Response (200 OK)：

{
  "status": "success",
  "message": "Agent deleted"
}

Agentic Workflow Architect Integration（Agent 工作流架构集成）

Agent 现在已经与 MuAPI Workflow 系统集成，可以参与复杂的架构规划。

1. Planning Phase（规划阶段）

当 Agent 收到宽泛目标（例如“构建电商品牌流水线”）时，会进入 Consultant Planning Phase。它会提出多个架构方向，并等待你批准后再构建工作流图。

2. Skill-Based Execution（基于技能的执行）

Agent 可以使用 skill_ids 触发工作流中的特定节点，成为聊天指令与基于图的自动化之间的智能桥梁。

Public Workflow Recipe Discovery（公开工作流配方发现）

外部 Agent（Claude、Cursor、自定义 LLM 应用）可以发现并获取 muapi assistant 自带的工作流配方，无需 API Key。这些配方是端到端的自然语言 SKILL.md 文件，会把多个 muapi 端点串成一个命名流程（例如 照片 → 3D 动作人偶、产品照片 → 电影感 10 秒广告、长视频 → 竖屏短片）。

这些配方与上方 /agents/skills 返回的原子技能不同：原子技能是分配给新建 Agent 的单项能力；配方则是 Agent 可以直接加载并执行的完整多步骤流程。

1. List All Recipes（列出所有配方）

Response (200 OK)：

{
  "skills": [
    {
      "name": "storyboard",
      "description": "Generate N keyframes for a short story or scene sequence (image only, no video).",
      "triggers": ["storyboard", "keyframes", "scene sequence"],
      "inputs": ["premise", "scenes", "style"],
      "estimated_credits": 0,
      "url": "/api/v1/agent-skills/storyboard"
    }
  ]
}

2. Fetch a Recipe Body（获取配方正文）

Response (200 OK)：

{
  "name": "storyboard",
  "description": "...",
  "inputs": { "premise": { "type": "text", "required": true, "description": "..." }, "scenes": { "type": "int", "default": 6 } },
  "trigger_keywords": ["storyboard", "keyframes"],
  "estimated_credits": 0,
  "body": "# Storyboard\n\nStep 1: ...\nStep 2: ...\n"
}

Response (404)：

{
  "detail": {
    "error": { "code": "SKILL_NOT_FOUND", "message": "Unknown skill: foo" },
    "available": ["3d-logo-animation", "action-figure-generator", "..."]
  }
}
Agent API Documentation — Muapi Docs