@everruns/ sdk (英语)
Everruns API 的 TypeScript SDK 版本.
安装
npm install @everruns/sdk
从代码调用您的代理
使用 AgentClient 从申请中调用一个代理。 它拿着密钥
(单位:千美元)evr_ak_...到达代理的会话,没有别的.
import { AgentClient } from "@everruns/sdk";
// Reads EVERRUNS_AGENT_URL and EVERRUNS_AGENT_KEY
const agent = new AgentClient();
// or: new AgentClient({ agentUrl: "https://app.everruns.com/api/v1/channels/apichan_...", credential: "evr_ak_..." })
// One call: creates a session, sends the message, waits for the turn
console.log(await agent.run("What can you do?"));
// Act for one of your application's users (the key needs the `end_user` permission)
const alice = agent.forEndUser("customer-42");
console.log(await alice.run("Where is my order?"));
// For a browser or mobile app, never ship the key: mint a short-lived runtime token
const { access_token } = await alice.runtimeToken();
// ...then, in the browser:
const browser = new AgentClient({
agentUrl: "https://app.everruns.com/api/v1/channels/apichan_...",
credential: access_token,
});
用于更多的控制用途 createSession, (中文(简体) ), sendMessage, (中文(简体) ), streamEvents, (中文(简体) ), listEvents, (中文(简体) ),
getSession, (中文(简体) ), cancel, (中文(简体) ), answerQuestions 财务报告和审定财务报表 submitToolApprovals。 。 。 .
以下管理客户Everruns,带有个人访问符号)
管理 Everruns : 代理,牵引,工作空间. 内容 sessions.create 财务报告和审定财务报表
messages.create 用于调用代理 AgentClient 换句话说.
管理快速启动
import { Everruns } from "@everruns/sdk";
// Uses EVERRUNS_API_KEY and optional EVERRUNS_ORG_ID environment variables
const client = Everruns.fromEnv();
// Create an agent
const agent = await client.agents.create({
name: "Assistant",
systemPrompt: "You are a helpful assistant."
});
// Create a session
const session = await client.sessions.create({ agentId: agent.id });
// Send a message
await client.messages.create(session.id, "Hello!");
// Stream events
for await (const event of client.events.stream(session.id)) {
console.log(event.type, event.data);
}
特工哈内斯
每个特工都拥有一副吊带 设定为创建/更新 harnessName (首选)或 harnessId (相互排斥); 省略两者以默认为 org 的 generic 绳子。 由代理创建的会话运行在代理的操纵上.
// Create an agent on a specific harness
const agent = await client.agents.create({
name: "researcher",
systemPrompt: "You do deep research.",
harnessName: "deep-research",
});
// Agent-first session: runs on the agent's harness
const session = await client.sessions.create({ agentName: "researcher" });
调用模型( M)
发现并管理被带,浏览可用的模型以选择一个 defaultModelId。 。 。 .
// Browse harnesses, then create one
const harnesses = await client.harnesses.list(); // or .search("research")
const harness = await client.harnesses.get(harnesses.data[0].id);
const custom = await client.harnesses.create({
name: "my-harness",
systemPrompt: "Base instructions for every session.",
});
const examples = await client.harnesses.listExamples();
// List models to pick a default for an agent
const models = await client.models.list();
初始文件
const session = await client.sessions.create({
agentId: "agent_...",
initialFiles: [
{
path: "/workspace/README.md",
content: "# Demo Project\n",
encoding: "text",
isReadonly: true,
},
{
path: "/workspace/src/app.py",
content: 'print("hello")\n',
encoding: "text",
},
],
});
可运行实例 : examples/initial-files.ts
从此 repo 从本地运行 npx tsx examples/initial-files.ts。 。 。 .
代理版本
const version = await client.agents.createVersion("agent_...", {
changeKind: "manual",
summary: "Baseline",
});
const versions = await client.agents.listVersions("agent_...");
const diff = await client.agents.diffVersions("agent_...", "agentver_1", version.id);
const fork = await client.agents.forkVersion("agent_...", version.id, {
name: "forked-agent",
});
const rollback = await client.agents.rollbackVersion("agent_...", version.id, {
saveVersion: true,
});
工作空间
工作区拥有各会场共享的文件.
const workspace = await client.workspaces.create({ name: "team-docs" });
await client.workspaceFiles.create(
workspace.id,
"/notes/welcome.md",
"# Welcome\n",
{ encoding: "text" },
);
const file = await client.workspaceFiles.read(workspace.id, "/notes/welcome.md");
const files = await client.workspaceFiles.list(workspace.id, { recursive: true });
可运行实例 : examples/workspaces.ts
从此 repo 从本地运行 npx tsx examples/workspaces.ts。 。 。 .
回忆
记忆是长期,可搜索的知识库,供代理商使用.
const memory = await client.memories.create({ name: "product-knowledge" });
await client.memories.createFile(memory.id, "/facts/product.md", {
content: "# Product\n",
encoding: "text",
});
const results = await client.memories.grepFiles(memory.id, "product");
await client.memories.sync(memory.id);
可运行实例 : examples/memories.ts
从此 repo 从本地运行 npx tsx examples/memories.ts。 。 。 .
认证
SDK使用个人访问令牌认证. 设定 EVERRUNS_API_KEY 环境变量或明确传递符号。 关于可进入多个组织的个人进入标志,设置 EVERRUNS_ORG_ID 或通过 orgId 明确:
// From environment variable
const client = Everruns.fromEnv();
或者有明确的标志和组织:
const client = new Everruns({
apiKey: "evr_pat_...",
orgId: "org_..."
});
变化原因
记下为什么做了改变. withReason 生成客户端发送
由它提出的每个 API 请求说明理由; 服务器将其保存在已更改的
实体的历史。 原客户端保持不变:
await client.withReason("retire the unused agent").agents.delete("agent_123");
const scoped = client.withReason("rotate prompts for the Q3 launch");
await scoped.agents.delete("agent_456");
其原因出现在 Everruns-Change-Reason uTF-8 标题
百分之百的编码。 空白的原因不会发出信头。 服务器用 HTTP 400 来修剪原因并拒绝它( Nameinvalid_change_reason当它超过1000个字符,包含除新行和标签以外的控制字符,或者看起来它包含一个证书.
流动事件
SDK支持 SSE 流出自动重联:
const stream = client.events.stream(session.id, {
exclude: ["output.message.delta"], // Filter out delta events
sinceId: "evt_..." // Resume from event ID
});
for await (const event of stream) {
switch (event.type) {
case "output.message.completed":
console.log("Message:", event.data);
break;
case "turn.completed":
console.log("Turn completed");
stream.abort(); // Stop streaming
break;
case "turn.failed":
console.error("Turn failed:", event.data);
break;
}
}
处理错误
import { ApiError, AuthenticationError, RateLimitError } from "@everruns/sdk";
try {
await client.agents.get("invalid-id");
} catch (error) {
if (error instanceof AuthenticationError) {
console.error("Invalid personal access token");
} else if (error instanceof RateLimitError) {
console.log(`Retry after ${error.retryAfter} seconds`);
} else if (error instanceof ApiError) {
console.error(`API error ${error.statusCode}: ${error.message}`);
}
}
许可证
麻省理工学院