Back to Details

handlebar-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Handlebar Connection Skill

Handlebar连接技能

Connect an AI agent to the Handlebar governance platform. This skill analyzes the agent codebase and prepares the information needed to configure governance in Handlebar.
将AI Agent连接到Handlebar治理平台。本技能会分析Agent代码库，准备在Handlebar中配置治理所需的信息。

When to Use

适用场景

Use this skill when the user wants to:
  • Connect an agent to Handlebar
  • Set up Handlebar governance
  • Onboard an agent to Handlebar
当用户需要完成以下操作时使用本技能：
  • 将Agent连接到Handlebar
  • 配置Handlebar治理规则
  • 将Agent接入Handlebar平台

Workflow

工作流程

Step 1: Handlebar Setup Information

步骤1：Handlebar设置信息

INFORM THE USER:
"To connect your agent to Handlebar, you'll need an account and API key:
Sign up: https://app.gethandlebar.com
(Handlebar is currently operating a waitlist - if you don't have access, email contact@gethandlebar.com to request it)
Create an API key: Org Settings > API Keys > Create API key
Set the environment variable:
bash
export HANDLEBAR_API_KEY=hb_your_api_key_here
# Or add to .env file
HANDLEBAR_API_KEY=hb_your_api_key_here
Don't worry if you don't have this yet - the API key can be added after we've onboarded your agent. Let's continue with the setup."
Proceed to Step 2.
告知用户：
"要将你的Agent连接到Handlebar，你需要一个账号和API密钥：
注册地址：https://app.gethandlebar.com
（Handlebar目前采用等待名单制，如果你还没有访问权限，可以发送邮件到contact@gethandlebar.com申请）
创建API密钥：组织设置 > API密钥 > 创建API密钥
设置环境变量：
bash
export HANDLEBAR_API_KEY=hb_your_api_key_here
# 或者添加到.env文件
HANDLEBAR_API_KEY=hb_your_api_key_here
如果你暂时还没有这些信息也不用担心，API密钥可以在我们完成Agent接入后再补充。我们先继续进行设置。"
进入步骤2。

Step 2: Detect Agent Framework

步骤2：检测Agent框架

Search the codebase for framework indicators:
FrameworkDetection PatternPackage
Vercel AI SDK v5+
"ai": "^5.x"
or 
import { Agent } from "ai"
@handlebar/ai-sdk-v5
LangChain JS
"@langchain/core"
or 
import { AgentExecutor }
@handlebar/langchain
LangChain Python
from langchain.X import Y
handlebar-langchain
Google ADK Python
from google.adk.X import Y
handlebar-google-adk
LlamaIndex TS
"llamaindex"
or 
import { FunctionTool }
Custom with 
@handlebar/core
OpenAI SDK
"openai"
with tool calls		Custom with 
@handlebar/core
Anthropic SDK
"@anthropic-ai/sdk"
with tool_use		Custom with 
@handlebar/core
Google Gemini
"@google/generative-ai"
Custom with 
@handlebar/core
CustomManual agent loop
@handlebar/core
Output: Report the detected framework to the user.
在代码库中搜索框架特征标识：
框架检测规则依赖包
Vercel AI SDK v5+
"ai": "^5.x"
或者 
import { Agent } from "ai"
@handlebar/ai-sdk-v5
LangChain JS
"@langchain/core"
或者 
import { AgentExecutor }
@handlebar/langchain
LangChain Python
from langchain.X import Y
handlebar-langchain
Google ADK Python
from google.adk.X import Y
handlebar-google-adk
LlamaIndex TS
"llamaindex"
或者 
import { FunctionTool }
基于
@handlebar/core
自定义
OpenAI SDK带工具调用的
"openai"
基于
@handlebar/core
自定义
Anthropic SDK带tool_use的
"@anthropic-ai/sdk"
基于
@handlebar/core
自定义
Google Gemini
"@google/generative-ai"
基于
@handlebar/core
自定义
自定义框架手动实现的Agent循环
@handlebar/core
输出：向用户报告检测到的框架。

Step 3: Configure Framework on Handlebar

步骤3：在Handlebar上配置框架

Based on detected framework, provide integration instructions. Some frameworks are supported directly with Handlebar packages. Those linked to a "core" package (
@handlebar/core
for JS and 
handlebar-core
for Python) do not yet have direct support, however they can still be integrated by connecting to the agent's lifecycle methods.
First, let's learn how to connect an agent. For a Javascript, Typescript, or Python agent:
根据检测到的框架，提供集成说明。部分框架可以直接通过Handlebar官方包支持。关联到"core"包的框架（JS使用
@handlebar/core
，Python使用
handlebar-core
）目前暂无直接支持，不过仍然可以通过对接Agent的生命周期方法完成集成。
首先我们来了解如何连接Agent，对于Javascript、Typescript或Python开发的Agent：

For Non-JavaScript/Python Agents

非JavaScript/Python开发的Agent

If the agent is built in a language other than JavaScript, TypeScript, or Python (e.g. Go, Rust, Java):
INFORM THE USER:
"[Language] is not yet supported by Handlebar SDKs.
Please contact the Handlebar team at contact@gethandlebar.com to let them know the agent framework you want to use. We will endeavour to support it as soon as possible.
In the meantime, let's continue with the agent and rule analysis so you're ready when support is available."
Then proceed to Step 4 to complete the codebase assessment.
如果Agent使用JavaScript、TypeScript、Python之外的语言开发（例如Go、Rust、Java）：
告知用户：
"Handlebar SDK暂时不支持[对应语言]开发的Agent。
请发送邮件到contact@gethandlebar.com联系Handlebar团队，告知你使用的Agent框架，我们会尽快提供支持。
在此期间，我们可以先完成Agent和规则分析，等支持开放后你就可以直接使用了。"
然后进入步骤4完成代码库评估。

Step 4: Assess Codebase for Agent Purpose

步骤4：评估代码库明确Agent用途

Analyze the agent to gather information for Handlebar configuration.
分析Agent以收集Handlebar配置所需的信息。

4.i: Tool Analysis

4.i 工具分析

For each tool in the agent, extract:
  1. Tool name
  2. Description - What does it do?
  3. Summary - One-line purpose
  4. Suggested categories from:
    • Data: 
      read
      , 
      write
      , 
      delete
    • Sensitivity: 
      pii
      , 
      phi
      , 
      financial
      , 
      sensitive
    • Scope: 
      internal
      , 
      external
    • Risk: 
      irreversible
      , 
      high-risk
    • Auth: 
      auth
      , 
      admin-only
      , 
      manager-only
Output format:
undefined
为Agent中的每个工具提取以下信息：
  1. 工具名称
  2. 描述 - 工具的功能是什么？
  3. 摘要 - 一行说明工具用途
  4. 建议分类，从以下选项中选择：
    • 数据操作：
      read
      、
      write
      、
      delete
    • 敏感度：
      pii
      、
      phi
      、
      financial
      、
      sensitive
    • 范围：
      internal
      、
      external
    • 风险：
      irreversible
      、
      high-risk
    • 权限：
      auth
      、
      admin-only
      、
      manager-only
输出格式：
undefined

Tool Analysis

工具分析

ToolSummaryCategories
getUserProfileFetches user profile dataread, pii, internal
issueRefundProcesses customer refundswrite, financial, irreversible
sendEmailSends email to customerwrite, external
undefined
工具摘要分类
getUserProfile获取用户资料数据read, pii, internal
issueRefund处理客户退款write, financial, irreversible
sendEmail向客户发送邮件write, external
undefined

4.ii: Agent Intent & Workflow

4.ii Agent意图与工作流

Based on the tool analysis above, determine what the agent is trying to accomplish:
Analyze:
  1. Primary workflow - What business process does this agent support?
    • Look at the combination of tools and how they would be used together
    • Consider the system prompt if available
    • Example: "Patient appointment booking and management"
  2. Agent goal - What is the agent ultimately trying to achieve for the user?
    • Example: "Help patients book, reschedule, or cancel appointments"
  3. Workflow stages - What steps does the agent typically take?
    • Example: "1. Verify patient identity → 2. Check availability → 3. Book appointment → 4. Send confirmation"
  4. Domain - What industry/sector does this agent operate in?
    • Healthcare, Finance, E-commerce, HR, Legal, Customer Support, etc.
Output format:
undefined
基于上述工具分析，确定Agent的业务目标：
分析维度：
  1. 核心工作流 - 该Agent支撑的业务流程是什么？
    • 结合工具的组合使用方式判断
    • 如果有系统提示词可作为参考
    • 示例："患者预约挂号与管理"
  2. Agent目标 - Agent最终要为用户实现什么价值？
    • 示例："帮助患者预约、改期或取消就诊"
  3. 工作流阶段 - Agent通常会执行哪些步骤？
    • 示例："1. 验证患者身份 → 2. 查询号源可用性 → 3. 预约挂号 → 4. 发送确认通知"
  4. 所属领域 - Agent运行在哪个行业/领域？
    • 医疗、金融、电商、人力资源、法律、客户支持等
输出格式：
undefined

Agent Intent & Workflow

Agent意图与工作流

Domain: Healthcare
Primary workflow: Patient appointment management
Agent goal: Help patients book, modify, and cancel appointments with their healthcare provider
Typical workflow:
  1. Verify patient identity (lookup_patient, verify_dob)
  2. Understand patient need (conversation)
  3. Check availability (check_slots)
  4. Book/modify/cancel appointment (book_appointment, cancel_appointment)
  5. Send confirmation (send_confirmation_sms, send_confirmation_email)
Key interactions:
  • Patient ↔ Agent: Conversational booking
  • Agent ↔ Clinical system: Appointment CRUD
  • Agent ↔ Patient: Notifications
undefined
所属领域：医疗
核心工作流：患者就诊预约管理
Agent目标：帮助患者预约、修改和取消与医疗服务提供者的就诊安排
典型工作流：
  1. 验证患者身份（lookup_patient、verify_dob）
  2. 了解患者需求（对话交互）
  3. 查询号源可用性（check_slots）
  4. 预约/修改/取消就诊（book_appointment、cancel_appointment）
  5. 发送确认通知（send_confirmation_sms、send_confirmation_email）
核心交互：
  • 患者 ↔ Agent：对话式预约
  • Agent ↔ 临床系统：预约增删改查
  • Agent ↔ 患者：通知推送
undefined

4.iii: Jurisdiction & User Impact

4.iii 司法管辖与用户影响

Look for indicators in the codebase:
Jurisdiction signals:
  • Regulatory references: 
    NHS
    , 
    HIPAA
    , 
    GDPR
    , 
    FCA
    , 
    PCI-DSS
  • Domain suffixes: 
    .nhs.uk
    , 
    .gov
    , 
    .eu
  • Currency: 
    £
    (UK), 
    $
    (US), 
    €
    (EU)
  • Phone formats: 
    +44
    (UK), 
    +1
    (US)
  • ID formats: NHS number, SSN, national ID patterns
User impact signals:
  • User types: patients, customers, employees, public
  • Data sensitivity: health records, financial data, personal info
  • Action severity: payments, deletions, account changes
Output format:
undefined
在代码库中查找相关标识：
司法管辖信号：
  • 监管法规引用：
    NHS
    、
    HIPAA
    、
    GDPR
    、
    FCA
    、
    PCI-DSS
  • 域名后缀：
    .nhs.uk
    、
    .gov
    、
    .eu
  • 货币符号：
    £
    （英国）、
    $
    （美国）、
    €
    （欧盟）
  • 电话格式：
    +44
    （英国）、
    +1
    （美国）
  • 证件格式：NHS编号、SSN、身份证号格式
用户影响信号：
  • 用户类型：患者、客户、员工、公众
  • 数据敏感度：健康记录、金融数据、个人信息
  • 操作严重程度：支付、删除、账户变更
输出格式：
undefined

Jurisdiction & User Impact

司法管辖与用户影响

Detected jurisdiction: UK (NHS references, £ currency, +44 phone format)
Users impacted: Patients
Data sensitivity:
  • PHI (health records)
  • PII (contact details)
Regulatory considerations:
  • UK GDPR
  • NHS Data Security and Protection Toolkit
  • Caldicott Principles
High-risk actions:
  • Book/cancel appointments (affects patient care)
  • Access medical records (PHI exposure)

If jurisdiction cannot be inferred, **ASK THE USER**:

> "I couldn't determine the jurisdiction from the codebase. Where will this agent operate?
> - UK
> - US  
> - EU
> - Other (please specify)"
检测到的司法辖区：英国（NHS引用、£货币符号、+44电话格式）
受影响用户：患者
数据敏感度：
  • PHI（健康记录）
  • PII（联系方式）
监管合规要求：
  • 英国GDPR
  • NHS数据安全与保护工具包
  • Caldicott原则
高风险操作：
  • 预约/取消就诊（影响患者诊疗）
  • 访问医疗记录（PHI泄露风险）

如果无法推断司法辖区，**询问用户**：

> "我无法从代码库中判断司法辖区，该Agent将在哪个地区运行？
> - 英国
> - 美国  
> - 欧盟
> - 其他（请说明）"

Step 5: Connect the agent code to Handlebar

步骤5：将Agent代码连接到Handlebar

According to the integration documentation you reviewed earlier, we will now connect the agent to Handlebar.
  1. Connect the minimal lifecycle hooks (either using the provided wrapper in a client library, or the lifecycle hooks defined in the core packages/custom integration). Let the Handlebar client use default values where possible: do NOT write out every config argument explicitly.
  2. Provide appropriate agent metadata: provide a slug to Handlebar based on the agent's purpose, and provide agent tags if possible
  3. If there is a clear user id passed into the agent flow already, then configure Handlebar with that enduser/actor ID. Otherwise, let your user know that Handlebar can be configured to track endusers, and inform the user of the code change they would need to make to enable that.
  4. Provide Handlebar the tool metadata according to the data you collected in previous steps.
根据你之前查阅的集成文档，我们现在将Agent连接到Handlebar。
  1. 对接最基础的生命周期钩子（可以使用客户端库提供的封装，或者核心包/自定义集成中定义的生命周期钩子）。尽可能使用Handlebar客户端的默认值：不要显式写出所有配置参数。
  2. 提供合适的Agent元数据：根据Agent用途生成Handlebar标识slug，尽可能提供Agent标签
  3. 如果Agent流程中已经有明确的用户ID传入，则用该终端用户/操作者ID配置Handlebar。否则告知用户Handlebar支持追踪终端用户，说明需要修改哪些代码来启用该功能。
  4. 根据之前步骤收集的数据，向Handlebar提供工具元数据。

Final Output

最终输出

Provide a summary report for Handlebar configuration and save it to a file for use by the rule generation skill.
Create 
.handlebar
folder within 
./claude
and save to 
.claude/.handlebar/agent-config.json
:
json
{
  "agent": {
    "slug": "[agent-slug]",
    "name": "[agent-name]",
    "framework": "[detected framework]",
    "package": "[package to install]"
  },
  "tools": [
    { "name": "toolName", "summary": "...", "categories": ["read", "pii"] }
  ],
  "intent": {
    "domain": "[healthcare/finance/etc.]",
    "workflow": "[primary workflow]",
    "goal": "[agent goal]"
  },
  "context": {
    "jurisdiction": "[UK/US/EU]",
    "users": "[who is impacted]",
    "regulations": ["regulation1", "regulation2"],
    "highRiskActions": ["action1", "action2"]
  }
}
Output to user:
undefined
提供Handlebar配置汇总报告，并保存到文件供规则生成技能使用。
在
./claude
目录下创建
.handlebar
文件夹，将配置保存到
.claude/.handlebar/agent-config.json
：
json
{
  "agent": {
    "slug": "[agent-slug]",
    "name": "[agent-name]",
    "framework": "[detected framework]",
    "package": "[package to install]"
  },
  "tools": [
    { "name": "toolName", "summary": "...", "categories": ["read", "pii"] }
  ],
  "intent": {
    "domain": "[healthcare/finance/etc.]",
    "workflow": "[primary workflow]",
    "goal": "[agent goal]"
  },
  "context": {
    "jurisdiction": "[UK/US/EU]",
    "users": "[who is impacted]",
    "regulations": ["regulation1", "regulation2"],
    "highRiskActions": ["action1", "action2"]
  }
}
输出给用户：
undefined

Handlebar Configuration Summary

Handlebar配置汇总

Agent

Agent信息

  • Framework: [detected framework]
  • Package: [package to install]
  • 框架：[检测到的框架]
  • 依赖包：[需要安装的包]

Tools

工具列表

ToolSummaryCategories
.........
工具摘要分类
.........

Intent

意图信息

  • Domain: [domain]
  • Workflow: [primary workflow]
  • Goal: [agent goal]
  • 所属领域：[领域]
  • 工作流：[核心工作流]
  • 目标：[Agent目标]

Context

上下文信息

  • Jurisdiction: [detected/specified]
  • Users: [who is impacted]
  • Regulations: [applicable regulations]
  • High-risk actions: [list]
  • 司法辖区：[检测到的/用户指定的辖区]
  • 受影响用户：[受影响的用户群体]
  • 监管要求：[适用的监管法规]
  • 高风险操作：[列表]

Next Steps

后续步骤

  1. Install the package: 
    npm install [package]
  2. Add the integration code (above)
  3. Run 
    /handlebar_rule_generation
    to generate governance rules
Configuration saved to 
.claude/.handlebar/agent-config.json

**ASK THE USER**:

> "Please review the configuration above. Is this information correct?
>
> - If yes, you can proceed with `/handlebar-rule-generation` to generate governance rules
> - If anything needs to be changed, let me know and I'll update the configuration
>
> **Important**: Only proceed with rule generation once you are satisfied that the information mentioned above is accurate and complete. This configuration will be saved to `.claude/.handlebar/agent-config.json` and the generated rules will be based on it, so any inaccuracies here will affect the quality of your governance rules."
  1. 安装依赖包：
    npm install [package]
  2. 添加集成代码（如上）
  3. 运行
    /handlebar_rule_generation
    生成治理规则
配置已保存到
.claude/.handlebar/agent-config.json

**询问用户**：

> "请检查上述配置，信息是否正确？
>
> - 如果正确，你可以运行`/handlebar-rule-generation`生成治理规则
> - 如果有需要修改的内容，请告诉我，我会更新配置
>
> **重要提示**：请确认上述信息准确完整后再进行规则生成。该配置会保存在`.claude/.handlebar/agent-config.json`中，生成的规则将基于该配置，因此任何不准确的信息都会影响治理规则的质量。"