API 块 YAML 模式

模式定义

type: object
required:
  - type
  - name
  - inputs
properties:
  type:
    type: string
    enum: [api]
    description: Block type identifier
  name:
    type: string
    description: Display name for this API block
  inputs:
    type: object
    required:
      - url
      - method
    properties:
      url:
        type: string
        description: The endpoint URL to send the request to
      method:
        type: string
        enum: [GET, POST, PUT, DELETE, PATCH]
        description: HTTP method for the request
        default: GET
      params:
        type: array
        description: Query parameters as table entries
        items:
          type: object
          required:
            - id
            - cells
          properties:
            id:
              type: string
              description: Unique identifier for the parameter entry
            cells:
              type: object
              required:
                - Key
                - Value
              properties:
                Key:
                  type: string
                  description: Parameter name
                Value:
                  type: string
                  description: Parameter value
      headers:
        type: array
        description: HTTP headers as table entries
        items:
          type: object
          required:
            - id
            - cells
          properties:
            id:
              type: string
              description: Unique identifier for the header entry
            cells:
              type: object
              required:
                - Key
                - Value
              properties:
                Key:
                  type: string
                  description: Header name
                Value:
                  type: string
                  description: Header value
      body:
        type: string
        description: Request body for POST/PUT/PATCH methods
      timeout:
        type: number
        description: Request timeout in milliseconds
        default: 30000
        minimum: 1000
        maximum: 300000
  connections:
    type: object
    properties:
      success:
        type: string
        description: Target block ID for successful requests
      error:
        type: string
        description: Target block ID for error handling

连接配置

连接定义了根据请求结果工作流的走向：

connections:
  success: <string>                     # Target block ID for successful requests
  error: <string>                       # Target block ID for error handling (optional)

示例

简单的 GET 请求

user-api:
  type: api
  name: "Fetch User Data"
  inputs:
    url: "https://api.example.com/users/123"
    method: GET
    headers:
      - id: header-1-uuid-here
        cells:
          Key: "Authorization"
          Value: "Bearer {{API_TOKEN}}"
      - id: header-2-uuid-here
        cells:
          Key: "Content-Type"
          Value: "application/json"
  connections:
    success: process-user-data
    error: handle-api-error

带有正文的 POST 请求

create-ticket:
  type: api
  name: "Create Support Ticket"
  inputs:
    url: "https://api.support.com/tickets"
    method: POST
    headers:
      - id: auth-header-uuid
        cells:
          Key: "Authorization"
          Value: "Bearer {{SUPPORT_API_KEY}}"
      - id: content-type-uuid
        cells:
          Key: "Content-Type"
          Value: "application/json"
    body: |
      {
        "title": "<agent.title>",
        "description": "<agent.description>",
        "priority": "high"
      }
  connections:
    success: ticket-created
    error: ticket-error

带查询参数的动态 URL

search-api:
  type: api
  name: "Search Products"
  inputs:
    url: "https://api.store.com/products"
    method: GET
    params:
      - id: search-param-uuid
        cells:
          Key: "q"
          Value: <start.searchTerm>
      - id: limit-param-uuid
        cells:
          Key: "limit"
          Value: "10"
      - id: category-param-uuid
        cells:
          Key: "category"
          Value: <filter.category>
    headers:
      - id: auth-header-uuid
        cells:
          Key: "Authorization"
          Value: "Bearer {{STORE_API_KEY}}"
  connections:
    success: display-results

参数格式

Headers 和 params（查询参数）使用以下结构的表格格式：

headers:
  - id: unique-identifier-here
    cells:
      Key: "Content-Type"
      Value: "application/json"
  - id: another-unique-identifier
    cells:
      Key: "Authorization"
      Value: "Bearer {{API_TOKEN}}"

params:
  - id: param-identifier-here
    cells:
      Key: "limit"
      Value: "10"

结构详情：

id：用于跟踪表格行的唯一标识符
cells.Key：参数/头部名称
cells.Value：参数/头部值
此格式允许正确的表格管理和 UI 状态的保存

输出参考

在 API 块执行后，可以在后续块中引用其输出。API 块提供三个主要输出：

可用输出

输出	类型	描述
`data`	any	API 的响应正文/负载
`status`	number	HTTP 状态码（200、404、500 等）
`headers`	object	服务器返回的响应头

使用示例

# Reference API response data
process-data:
  type: function
  name: "Process API Data"
  inputs:
    code: |
      const responseData = <fetchuserdata.data>;
      const statusCode = <fetchuserdata.status>;
      const responseHeaders = <fetchuserdata.headers>;
      
      if (statusCode === 200) {
        return {
          success: true,
          user: responseData,
          contentType: responseHeaders['content-type']
        };
      } else {
        return {
          success: false,
          error: `API call failed with status ${statusCode}`
        };
      }

# Use API data in an agent block
analyze-response:
  type: agent
  name: "Analyze Response"
  inputs:
    userPrompt: |
      Analyze this API response:
      
      Status: <fetchuserdata.status>
      Data: <fetchuserdata.data>
      
      Provide insights about the response.

# Conditional logic based on status
check-status:
  type: condition
  name: "Check API Status"
  inputs:
    condition: <fetchuserdata.status> === 200
  connections:
    true: success-handler
    false: error-handler

实际示例

user-api:
  type: api
  name: "Fetch User Data"
  inputs:
    url: "https://api.example.com/users/123"
    method: GET
  connections:
    success: process-response

process-response:
  type: function
  name: "Process Response"
  inputs:
    code: |
      const user = <fetchuserdata.data>;
      const status = <fetchuserdata.status>;
      
      console.log(`API returned status: ${status}`);
      console.log(`User data:`, user);
      
      return {
        userId: user.id,
        email: user.email,
        isActive: status === 200
      };

错误处理

api-with-error-handling:
  type: api
  name: "API Call"
  inputs:
    url: "https://api.example.com/data"
    method: GET
  connections:
    success: check-response
    error: handle-error

check-response:
  type: condition
  name: "Check Response Status"
  inputs:
    condition: <apicall.status> >= 200 && <apicall.status> < 300
  connections:
    true: process-success
    false: handle-api-error

process-success:
  type: function
  name: "Process Success"
  inputs:
    code: |
      return {
        success: true,
        data: <apicall.data>,
        message: "API call successful"
      };

handle-api-error:
  type: function
  name: "Handle API Error"
  inputs:
    code: |
      return {
        success: false,
        status: <apicall.status>,
        error: "API call failed",
        data: <apicall.data>
      };

YAML 字符串转义

在编写 YAML 时，某些字符串必须加引号才能被正确解析：

必须加引号的字符串

# URLs with hyphens, colons, special characters
url: "https://api.example.com/users/123"
url: "https://my-api.example.com/data"

# Header values with hyphens or special characters  
headers:
  - id: header-uuid
    cells:
      Key: "User-Agent"
      Value: "My-Application/1.0"
  - id: auth-uuid
    cells:
      Key: "Authorization" 
      Value: "Bearer my-token-123"

# Parameter values with hyphens
params:
  - id: param-uuid
    cells:
      Key: "sort-by"
      Value: "created-at"

何时使用引号

✅ 始终加引号：URL、令牌、包含连字符、冒号或特殊字符的值
✅ 始终加引号：以数字开头但应为字符串的值
✅ 始终加引号：看似布尔值但应保持为字符串的值
❌ 不要加引号：不含特殊字符的简单字母数字字符串

示例

# ✅ Correct
url: "https://api.stripe.com/v1/charges"
headers:
  - id: auth-header
    cells:
      Key: "Authorization"
      Value: "Bearer sk-test-123456789"

# ❌ Incorrect (may cause parsing errors)
url: https://api.stripe.com/v1/charges
headers:
  - id: auth-header
    cells:
      Key: Authorization
      Value: Bearer sk-test-123456789

最佳实践

使用环境变量存储 API 密钥：{{API_KEY_NAME}}
包含错误连接的错误处理
为您的用例设置适当的超时时间
在后续块中验证响应状态码
使用有意义的块名称以便于参考
始终为包含特殊字符、URL 和令牌的字符串加引号

API 块 YAML 模式

On this page