Configuration

Agent runtime settings live in AgentConfig. Directory metadata, such as the display title, lives outside config.

CreateAgentInput

interface CreateAgentInput {
  title?: string;
  config?: AgentConfig;
}

const agent = await app.agents.create({
  title: "Research assistant",
  config: {
    modelTier: "fast",
    instructions: "Be concise and cite sources.",
  },
});

AgentConfig

interface AgentConfig {
  modelProvider?: string;
  modelTier?: "fast" | "capable";
  model?: string;
  instructions?: string;
  maxSteps?: number;
  extensions?: ExtensionDefinition[];
  capabilities?: CapabilityDefinition[];
}

Models

Use model for an explicit provider/model id, or modelTier for a runtime-selected default.

await agent.updateConfig({
  model: "anthropic/claude-sonnet-4",
});

await agent.updateConfig({
  modelTier: "fast",
});

Instructions

await agent.updateConfig({
  instructions: "You are a product research assistant.",
});

Extensions

Extensions define additional runtime tools.

await agent.updateConfig({
  extensions: [
    {
      environment: "agent",
      name: "summarize_input",
      description: "Summarize a text input.",
      parameters: {
        type: "object",
        properties: {
          text: { type: "string" },
        },
        required: ["text"],
      },
      code: `
export default async function ({ text }) {
  return String(text).slice(0, 500);
}
`,
    },
  ],
});

Capabilities

Capabilities describe the runtime permissions an agent can use.

await agent.updateConfig({
  capabilities: [
    "read",
    "write",
    {
      environment: "agent",
      capabilities: ["execute", "network"],
    },
  ],
});

Type Reference

type Environment = "agent" | "app";

interface ExtensionDefinition {
  environment?: Environment;
  name: string;
  description?: string;
  parameters?: JsonSchema;
  code?: string;
}

type Capability = "read" | "write" | "execute" | "database" | "network" | "secret" | "browser";

type CapabilityDefinition =
  | Capability
  | {
      environment?: Environment;
      capabilities: Capability[];
    };