AMP 类型脚本 SDK

使用 Amp SDK 程序在您运行 TypeScript 的任何地方部署 Amp 代理 。 执行 AMP CLI 在程序上命令全类型安全,流回响应,并完全控制您的 AI 编码代理工作流程.

为什么用Amp SDK?

Amp TypeScript SDK 将 Amp 代理直接带入您的应用程序, 具有简单可靠的功能 :

• 串流输入: 递增向 Amp 代理发送提示和信件
• 连续产出: 接收结构化的 JSON 响应( 系统, 助手, 结果), 因为代理执行任务
• 多回合对话:在多次处决之间保持前后互动
• 线条连续性: 继续一个已存在的线程( 最新或通过 ID) 来构建状态代理工作流程
• 程序设置: 配置没有用户提示的工作目录、设置和工具——自动化的理想
• MCP 一体化: 使用自定义的模型上下文协议服务器和工具扩展 Amp
• 自定义技能: 定义并使用自定义代理技能来扩展 Amp 的功能

你能造出什么来?

Amp SDK 启用了广泛的AI驱动应用程序:

开发工具

• 代码审查代理:自动拉动请求分析和反馈
• 文档生成器: 创建和维护项目文档
• 测试自动化: 生成并执行测试套件
• 移徙助理: 帮助更新代码库并重构遗留代码

工作流程自动化

• CI/CD 一体化:智能建设和部署管道
• 问题 Trage: 自动分类和优先排序错误报告
• 守则质量监测:持续分析代码健康衡量标准
• 发行管理: 自动更改日志生成和版本起伏

快速启动

安装

# Install the Amp SDK using npm
npm install @ampcode/sdk

# or yarn
yarn add @ampcode/sdk

# Optional: manually install the Amp CLI, already a dependency
npx -y @ampcode/sdk install

如果您需要在 Amp Neo 之前使用 Amp, 请安装遗留的 SDK 发布 @ampcode/[email protected]数字 :

npm install @ampcode/[email protected]

SDK需要一个Amp CLI版本,该版本至少是被您SDK发布所支撑的版本. 狦 组织通过Homebrew,Artifactory或另一个内部分配通道安装 AMP CLI, 您可以继续使用该安装,只要其版本足够新.

安装后, 请将您的 API 密钥添加到环境中 。 您可以访问您的 API 密钥 安全设置。 。 。 .

export AMP_API_KEY=sgamp_your_api_key_here

您的第一个 AMP 命令

现在您已经安装了 SDK 并设置了您的 API 密钥, 您可以开始使用 Amp execute() 函数 :

import { execute } from '@ampcode/sdk'

// Simple execution - get the final result
for await (const message of execute({ prompt: 'What files are in this directory?' })) {
    if (message.type === 'result' && !message.is_error) {
        console.log('Result:', message.result)
        break
    }
}

这个 execute() 函数仅需要您提供 prompt 要开始。 SDK 串流消息作为代理工作,让你处理响应并直接将其集成到您的应用程序中.

核心概念

信件流

在您的代理执行时, SDK 流出不同类型的消息 :

for await (const message of execute({ prompt: 'Run tests' })) {
    if (message.type === 'system') {
        // Session info, available tools, MCP servers
        console.log('Available tools:', message.tools)
    } else if (message.type === 'assistant') {
        // AI responses and tool usage
        console.log('Assistant is working...')
    } else if (message.type === 'result') {
        // Final result (success or error)
        console.log('Done:', message.result)
    }
}

简单结果提取

当你只需要最后的结果而不处理流:

async function getResult(prompt: string): Promise<string> {
    for await (const message of execute({ prompt })) {
        if (message.type === 'result') {
            if (message.is_error) {
                throw new Error(message.error)
            }
            return message.result
        }
    }
    throw new Error('No result received')
}

// Usage
try {
    const result = await getResult('List all TypeScript files in this project')
    console.log('Found files:', result)
} catch (error) {
    console.error('Failed:', error.message)
}

线条连续性

继续跨越多种互动的对话 :

// Continue the most recent conversation
for await (const message of execute({
    prompt: 'What was the last error you found?',
    options: { continue: true },
})) {
    if (message.type === 'result') {
        console.log(message.result)
    }
}

// Continue a specific thread by ID
for await (const message of execute({
    prompt: 'Can you update that code we discussed?',
    options: { continue: 'T-abc123-def456' },
})) {
    if (message.type === 'result') {
        console.log(message.result)
    }
}

常见配置

工作目录

指定 Amp 运行位置 :

for await (const message of execute({
    prompt: 'Refactor the auth module',
    options: { cwd: './my-project' },
})) {
    // Process messages...
}

启用调试日志

看看车盖下面发生了什么

for await (const message of execute({
    prompt: 'Analyze this project',
    options: {
        logLevel: 'debug', // Shows CLI command in console
        logFile: './amp-debug.log', // Optional: write logs to file
    },
})) {
    // Process messages
}

代理模式

选择要使用的代理模式 。 模式控制模型、系统提示和工具选择 :

for await (const message of execute({
    prompt: 'Quickly fix this typo',
    options: {
        mode: 'low', // Use low mode for faster responses
    },
})) {
    // Process messages
}

可用模式 :

• low: 快速、低成本模式,用于定义清晰的小型任务
• medium (默认):大多数任务的默认,平衡质量,速度和成本
• high: 用于需要更深入推理并能容忍更多时间和成本的困难任务
• ultra: 当最大能力比速度或成本更重要时,用于最困难的开放式任务

努力的理由

设置支持模式的模型推理工作 :

for await (const message of execute({
    prompt: 'Think carefully and explain your plan before coding.',
    options: {
        mode: 'medium',
        effort: 'high',
    },
})) {
    if (message.type === 'result') {
        console.log(message.result)
        break
    }
}

现有努力水平:

• none
• minimal
• low
• medium
• high
• xhigh
• max

线索标签

将标签添加到线程中 execute()。 。 。 .

for await (const message of execute({
    prompt: 'Summarize this repo',
    options: {
        labels: ['sdk', 'summary'],
    },
})) {
    if (message.type === 'result') {
        console.log(message.result)
        break
    }
}

线索标题

创建线程时设定标题 。 您无法使用 title 当继续一条线.

for await (const message of execute({
    prompt: 'Review pull request 42',
    options: {
        executor: 'orb',
        title: 'Review acme/widgets#42',
    },
})) {
    if (message.type === 'result') {
        console.log(message.result)
        break
    }
}

远程执行器

默认情况下,代理运行在本地 APP CLI 进程中. 设定 executor: 'orb' 运行在 Amp 中 云沙盒,或 executor: 'runner' 与 runnerId 运行在您启动的 AMP CLI 跑取器上 与 amp --no-tui --runner-id <id>在这两种情况下,地方进程只产生结果. 要求数 AMP_API_KEY。 。 。 .

for await (const message of execute({
    prompt: 'Run the integration tests and summarize any failures',
    options: {
        executor: 'runner',
        runnerId: 'build-box-1',
        runnerDir: '/home/build/code/my-project',
    },
})) {
    if (message.type === 'result') {
        console.log(message.result)
        break
    }
}

runnerDir 选择一个由跑者服务的绝对目录。 开始跑步 与 --dir /home/build/code/my-project,或者通过跑道发现来注册目录,或者 amp runner dirs add。关闭使用跑者起始目录的选项. 每个线程都有一个工作目录. 要在多个目录中运行, 请分别 execute() 打电话 继续线程保留其已存在的目录并忽略此选项 . cwd 只设定 本地 CLI 子进程目录; 它不选择运行器上的目录.

project 仅适用于 executor: 'orb'。 。 。 . 只有本地选项( O)permissions, (中文(简体) ), enabledTools, (中文(简体) ), skills, (中文(简体) ), mcpConfig, (中文(简体) ), dangerouslyAllowAll(中文(简体) ) 而流出输入提示不适用于远程执行器。 插件代理模式必须装入 跑垒的.

线索可见度

控制谁可以看到线程由 execute()数字 :

for await (const message of execute({
    prompt: 'Analyze this private codebase',
    options: {
        visibility: 'private', // Only you can see this thread
    },
})) {
    if (message.type === 'result') {
        console.log(message.result)
        break
    }
}

可用可见度 :

• workspace (默认):所有工作空间成员可见
• private: 只有你看得见
• unlisted: 任何有链接的人都能看到
• group: 显示您的用户组成员( 企业)

工具权限

使用一个 自定义插件 用于控制工具的使用. 工作空间管理员可以将其作为一个 全局工作空间插件。 。 。 .

高级使用

互动进展跟踪

用于构建显示实时进度的用户界面:

async function executeWithProgress(prompt: string) {
    console.log('Starting task...')

    for await (const message of execute({ prompt })) {
        if (message.type === 'system' && message.subtype === 'init') {
            console.log('Tools available:', message.tools.join(', '))
        } else if (message.type === 'assistant') {
            // Show tool usage or assistant responses
            const content = message.message.content[0]
            if (content.type === 'tool_use') {
                console.log(`Using ${content.name}...`)
            } else if (content.type === 'text') {
                console.log('Assistant:', content.text.slice(0, 100) + '...')
            }
        } else if (message.type === 'result') {
            if (message.is_error) {
                console.log('Failed:', message.error)
            } else {
                console.log('Completed successfully!')
                console.log(message.result)
            }
        }
    }
}

取消和超时

优雅地处理长期运作:

async function executeWithTimeout(prompt: string, timeoutMs = 30000) {
    const signal = AbortSignal.timeout(timeoutMs)

    try {
        for await (const message of execute({
            prompt,
            signal,
        })) {
            if (message.type === 'result') {
                return message.result
            }
        }
    } catch (error) {
        if (error.message.includes('aborted')) {
            throw new Error(`Operation timed out after ${timeoutMs}ms`)
        }
        throw error
    }
}

MCP(模式背景协议) 整合

使用自定义工具和数据源扩展 Amp 的能力 :

import { execute, type MCPConfig } from '@ampcode/sdk'

const mcpConfig: MCPConfig = {
    playwright: {
        command: 'npx',
        args: ['-y', '@playwright/mcp@latest', '--headless'],
        env: { NODE_ENV: 'production' },
    },
    database: {
        command: 'node',
        args: ['./custom-mcp-server.js'],
        env: { DB_CONNECTION_STRING: '${DATABASE_URL}' },
    },
}

for await (const message of execute({
    prompt: 'Test the login flow on staging environment',
    options: { mcpConfig },
})) {
    if (message.type === 'system') {
        console.log(
            'MCP Servers:',
            message.mcp_servers.map((s) => `${s.name}: ${s.status}`),
        )
    }
    // Handle other messages...
}

偏爱 ${VAR} 用于连接字符串和 API 令牌等秘密的占位符。 Amp在启动每个 MCP 服务器时从它的环境下扩展它们,所以秘密值从不需要出现在配置本身中. 占位符在 stdio 工作 command, (中文(简体) ), args,以及 env 在远程服务器中 url 财务报告和审定财务报表 headers 数值.

要了解更多关于使用 MCP 服务器扩展 Amp 的信息, 请访问 MCP 配置 部分.

多回合对话

使用同步生成器构建流式对话框 :

import { execute, createUserMessage } from '@ampcode/sdk'

async function* generateMessages() {
    yield createUserMessage('Start analyzing the codebase')

    // Wait for some condition or user input
    await new Promise((resolve) => setTimeout(resolve, 1000))

    yield createUserMessage('Now focus on the authentication module')
}

for await (const message of execute({
    prompt: generateMessages(),
})) {
    if (message.type === 'result') {
        console.log(message.result)
    }
}

设置文件配置

配置 Amp 设置文件的行为, 如 settings.json。 您可以为 Amp 提供您在工程中保存的自定义设置文件 :

import { execute } from '@ampcode/sdk'

// Use a custom settings file
for await (const message of execute({
    prompt: 'Deploy the application',
    options: {
        settingsFile: './settings.json',
        logLevel: 'debug',
    },
})) {
    // Handle messages...
}

示例 settings.json数字 :

{
    "amp.mcpServers": {
        "playwright": {
            "command": "npx",
            "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]
        }
    },
    "amp.tools.disable": ["web_search", "mcp__playwright__browser_resize"]
}

要找到所有可用的设置,请参见 配置设置。 。 。 .

自定义技能

从指定的目录装入自定义技能 :

for await (const message of execute({
    prompt: 'Use my custom deployment skill',
    options: {
        skills: './my-skills', // Path to custom skills directory
    },
})) {
    // Process messages
}

要多学习如何创造定制技能,请参看 代理技能 amp文档的章节.

职能

执行( )

在程序上执行 AMP CLI 命令的主要功能.

function execute(options: ExecuteOptions): AsyncIterable<StreamMessage>

参数

• options (单位:千美元)ExecuteOptions) - 执行配置

回返

• AsyncIterable<StreamMessage> - Amp CLI 的讯息流

示例

import { execute } from '@ampcode/sdk'

for await (const message of execute({
    prompt: 'Analyze this codebase',
    options: {
        cwd: './my-project',
    },
})) {
    if (message.type === 'assistant') {
        console.log('Assistant:', message.message.content)
    } else if (message.type === 'result') {
        console.log('Final result:', message.result)
        break
    }
}

创建 UserMessage ()

帮助器功能为流畅的对话创建适当的格式化的用户输入消息.

function createUserMessage(text: string, options?: { requestId?: string }): UserInputMessage

参数

• text (单位:千美元)string) - 用户消息的文本内容
• options.requestId (单位:千美元)string,可选) - A 1–256字符ID. 重用它进行重试 相同的线程可以防止 Amp 创建另一个用户消息.

回返

• UserInputMessage - 格式化用户输入信息

示例

import { createUserMessage } from '@ampcode/sdk'

const message = createUserMessage('Analyze this code', { requestId: 'analysis-123' })
console.log(message)
// Output: { type: 'user', requestId: 'analysis-123', message: { role: 'user', content: [{ type: 'text', text: 'Analyze this code' }] } }

线程. new ()

创建新空线索并返回其ID .

async function threads.new(options?: ThreadsNewOptions): Promise<string>

参数

• options (单位:千美元)ThreadsNewOptions,可选) - 新线程配置

回返

• Promise<string> - 线程标识

示例

import { threads } from '@ampcode/sdk'

// Create a new private thread
const threadId = await threads.new({ visibility: 'private' })
console.log('Created thread:', threadId)

线程. markdown ()

得到一条线导出 作为标记下.

async function threads.markdown(options: ThreadsMarkdownOptions): Promise<string>

参数

• options (单位:千美元)ThreadsMarkdownOptions- 包含线程ID的选项

回返

• Promise<string> - 线程内容作为标记下

示例

import { threads } from '@ampcode/sdk'

// Get thread content as markdown
const markdown = await threads.markdown({ threadId: 'T-abc123-def456' })
console.log(markdown)

线程. set多玩家( )

打开或关闭一条贡献线条(多玩家). 只工作于有共享(非私有)能见度的 Orb 线程和共享-runner 线程,并且只用于线程所有者.

async function threads.setMultiplayer(options: ThreadsSetMultiplayerOptions): Promise<void>

参数

• options (单位:千美元)ThreadsSetMultiplayerOptions) - 线程ID,启用的旗帜,以及可选的打开窗口持续时间

回返

• Promise<void>

示例

import { threads } from '@ampcode/sdk'

// Open a thread for contributions for the default duration (currently 3 hours)
await threads.setMultiplayer({ threadId: 'T-abc123-def456' })

// Open a thread for contributions for 12 hours
await threads.setMultiplayer({ threadId: 'T-abc123-def456', hours: 12 })

// Close a thread for contributions
await threads.setMultiplayer({ threadId: 'T-abc123-def456', enabled: false })

类型

执行选项

配置选项 execute() 函数.

interface ExecuteOptions {
    prompt: string | AsyncIterable<UserInputMessage>
    options?: AmpOptions
    signal?: AbortSignal
}

属性

选项

配置映射到 AMP CLI 旗的选项 .

interface AmpOptions {
    cwd?: string
    mode?: string // Prefer 'low', 'medium', 'high', or 'ultra'
    effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    noArchiveAfterExecute?: boolean
    visibility?: 'private' | 'unlisted' | 'workspace' | 'group'
    settingsFile?: string
    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'audit'
    logFile?: string
    mcpConfig?: string | MCPConfig
    env?: Record<string, string>
    continue?: boolean | string
    skills?: string
    enabledTools?: string[]
    labels?: string[]
    thinking?: boolean
    executor?: 'local' | 'orb' | 'runner'
    runnerId?: string
    runnerDir?: string
    project?: string
    title?: string
}

内置模式是 'low', (中文(简体) ), 'medium', (中文(简体) ), 'high',以及 'ultra'。也可以通过 自定义插件定义模式的字符串 .

属性

信件类型

SDK在执行期间流出各种消息类型. 所有消息都执行基础 StreamMessage 类型.

系统信息

包含会话信息和可用工具的初始信息.

interface SystemMessage {
    type: 'system'
    subtype: 'init'
    session_id: string
    cwd: string
    tools: string[]
    mcp_servers: Array<{
        name: string
        status: 'connected' | 'connecting' | 'connection-failed' | 'disabled'
    }>
}

属性

助理秘书

AI助理回应,包含文本内容和工具使用.

interface AssistantMessage {
    type: 'assistant'
    session_id: string
    message: {
        id: string
        type: 'message'
        role: 'assistant'
        model: string
        content: Array<TextContent | ToolUseContent>
        stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | null
        stop_sequence: string | null
        usage?: Usage
    }
    parent_tool_use_id: string | null
}

属性

用户信息

用户输入和工具结果.

interface UserMessage {
    type: 'user'
    session_id: string
    message: {
        role: 'user'
        content: Array<TextContent | ToolResultContent>
    }
    parent_tool_use_id: string | null
}

属性

结果

最终成功执行结果.

interface ResultMessage {
    type: 'result'
    subtype: 'success'
    session_id: string
    is_error: false
    result: string
    duration_ms: number
    num_turns: number
    usage?: Usage
    permission_denials?: string[]
}

属性

错误结果

显示执行失败的最终出错结果 .

interface ErrorResultMessage {
    type: 'result'
    subtype: 'error_during_execution' | 'error_max_turns'
    session_id: string
    is_error: true
    error: string
    duration_ms: number
    num_turns: number
    usage?: Usage
    permission_denials?: string[]
}

属性

文本关联

纯文本内容块.

interface TextContent {
    type: 'text'
    text: string
}

工具使用关联

工具执行请求 .

interface ToolUseContent {
    type: 'tool_use'
    id: string
    name: string
    input: Record<string, unknown>
}

工具结果关联

工具执行的结果 .

interface ToolResultContent {
    type: 'tool_result'
    tool_use_id: string
    content: string
    is_error: boolean
}

使用量

从API电话调用和计费信息.

interface Usage {
    input_tokens: number
    cache_creation_input_tokens?: number
    cache_read_input_tokens?: number
    output_tokens: number
    service_tier?: string
}

属性

输入类型

用户输入信

用于流媒体对话的已格式化用户输入消息 .

interface UserInputMessage {
    type: 'user'
    requestId?: string
    message: {
        role: 'user'
        content: Array<{
            type: 'text'
            text: string
        }>
    }
}

MCPONFIG 中东欧

MCP(模式上下文协议)服务器配置 。 支持基于stdio和基于HTTP的服务器.

type MCPConfig = Record<string, MCPServer>

// MCPServer is a union of stdio and HTTP server configurations

MCPServer 接受一个 stdio 服务器配置( 使用 command)或 HTTP 服务器配置(与 url:

const mcpConfig: MCPConfig = {
    playwright: { command: 'npx', args: ['-y', '@playwright/mcp'] },
    remote: { url: 'https://api.example.com/mcp' },
}

MCPServer 属性

Stdio 服务器 :

HTTP 服务器 :

OAuth 配置( 用于 HTTP 服务器) :

新选项

创建新线程的选项 .

interface ThreadsNewOptions {
    visibility?: 'private' | 'unlisted' | 'workspace' | 'group'
}

属性

线索马克倒置选项

获取线程标记的选项 .

interface ThreadsMarkdownOptions {
    threadId: string
}

属性

线索设置多玩家选项

为贡献打开或关闭线索的选项(多玩家). 期限选项为总和;总数必须在5分钟至7天之间。 何时 enabled 实值 true 而不给出持续时间,则使用服务器默认值(目前为3小时). 当 enabled 实值 false。 。 。 .

interface ThreadsSetMultiplayerOptions {
    threadId: string
    enabled?: boolean
    minutes?: number
    hours?: number
    days?: number
    weeks?: number
}

属性

所需资源

• 节点.js 18或以上