@statelyai/agent 1.1.6 → 2.0.0-next.1

package/.changeset/cyan-carpets-perform.md

@@ -0,0 +1,5 @@
+---
+'@statelyai/agent': patch
+---
+
+The `name` field in `createAgent({ name: '...' })` has been renamed to `id`.

package/.changeset/fast-donkeys-argue.md

@@ -0,0 +1,5 @@
+---
+"@statelyai/agent": patch
+---
+
+The `description` field in `createAgent({ description: '...' })` is now used for the `system` prompt in agent decision making when a `system` prompt is not provided.

package/.changeset/light-hats-drive.md

@@ -0,0 +1,9 @@
+---
+'@statelyai/agent': major
+---
+
+- `agent.generateText(…)` is removed in favor of using the AI SDK's `generateText(…)` function with a wrapped model.
+- `agent.streamText(…)` is removed in favor of using the AI SDK's `streamText(…)` function with a wrapped model.
+- Custom adapters are removed for now, but may be re-added in future releases. Using the AI SDK is recommended for now.
+- Correlation IDs are removed in favor of using [OpenTelemetry with the AI SDK](https://sdk.vercel.ai/docs/ai-sdk-core/telemetry#telemetry).
+- The `createAgentMiddleware(…)` function was introduced to facilitate agent message history. You can also use `agent.wrap(model)` to wrap a model with Stately Agent middleware.

package/.changeset/old-jobs-check.md

@@ -0,0 +1,5 @@
+---
+'@statelyai/agent': minor
+---
+
+You can specify `maxAttempts` in `agent.decide({ maxAttempts: 5 })`. This will allow the agent to attempt to make a decision up to the specified number of `maxAttempts` before giving up. The default value is `2`.

package/.changeset/pre.json

@@ -0,0 +1,13 @@
+{
+  "mode": "pre",
+  "tag": "next",
+  "initialVersions": {
+    "@statelyai/agent": "1.1.6"
+  },
+  "changesets": [
+    "cyan-carpets-perform",
+    "fast-donkeys-argue",
+    "light-hats-drive",
+    "old-jobs-check"
+  ]
+}

package/.vscode/launch.json

@@ -20,8 +20,14 @@
       "program": "${file}",
       "cwd": "${workspaceFolder}",
       "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/ts-node",
+      "runtimeArgs": ["--transpile-only", "-r", "dotenv/config"],
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
       "sourceMaps": true,
+      "smartStep": true,
+      "resolveSourceMapLocations": [
+        "${workspaceFolder}/**",
+        "!**/node_modules/**"
+      ],
       "console": "integratedTerminal"
     }
   ]

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @statelyai/agent
 
+## 2.0.0-next.1
+
+### Minor Changes
+
+- [`6a9861d`](https://github.com/statelyai/agent/commit/6a9861d959ce295114f53c95c5bdaa097348bacb) Thanks [@davidkpiano](https://github.com/davidkpiano)! - You can specify `maxAttempts` in `agent.decide({ maxAttempts: 5 })`. This will allow the agent to attempt to make a decision up to the specified number of `maxAttempts` before giving up. The default value is `2`.
+
+### Patch Changes
+
+- [`8c3eab8`](https://github.com/statelyai/agent/commit/8c3eab8950cb85e662c6afb5d8cefb1d5ef54dd8) Thanks [@davidkpiano](https://github.com/davidkpiano)! - The `name` field in `createAgent({ name: '...' })` has been renamed to `id`.
+
+- [`8c3eab8`](https://github.com/statelyai/agent/commit/8c3eab8950cb85e662c6afb5d8cefb1d5ef54dd8) Thanks [@davidkpiano](https://github.com/davidkpiano)! - The `description` field in `createAgent({ description: '...' })` is now used for the `system` prompt in agent decision making when a `system` prompt is not provided.
+
+## 2.0.0-next.0
+
+### Major Changes
+
+- [#51](https://github.com/statelyai/agent/pull/51) [`574b6fd`](https://github.com/statelyai/agent/commit/574b6fd62e8a41df311aa1ea00fae60c32ad595e) Thanks [@davidkpiano](https://github.com/davidkpiano)! - - `agent.generateText(…)` is removed in favor of using the AI SDK's `generateText(…)` function with a wrapped model.
+  - `agent.streamText(…)` is removed in favor of using the AI SDK's `streamText(…)` function with a wrapped model.
+  - Custom adapters are removed for now, but may be re-added in future releases. Using the AI SDK is recommended for now.
+  - Correlation IDs are removed in favor of using [OpenTelemetry with the AI SDK](https://sdk.vercel.ai/docs/ai-sdk-core/telemetry#telemetry).
+  - The `createAgentMiddleware(…)` function was introduced to facilitate agent message history. You can also use `agent.wrap(model)` to wrap a model with Stately Agent middleware.
+
 ## 1.1.6
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { EventObject, AnyStateMachine, AnyEventObject, AnyActorRef, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, ActorRefFrom, Subscription, StateValue, ObservableActorLogic } from 'xstate';
+import * as ai from 'ai';
+import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, LanguageModelV1, CoreTool } from 'ai';
+import { EventObject, AnyStateMachine, AnyEventObject, ActorRefLike, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, StateValue, Actor, Subscription, ObservableActorLogic } from 'xstate';
 import { SomeZodObject, ZodType, TypeOf } from 'zod';
-import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, StreamTextResult, CoreTool } from 'ai';
 
 type ZodEventMapping = {
     [eventType: string]: SomeZodObject;
@@ -11,7 +12,8 @@ type ZodContextMapping = {
 
 type GenerateTextOptions = Parameters<typeof generateText>[0];
 type StreamTextOptions = Parameters<typeof streamText>[0];
-type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'prompt' | 'messages' | 'tools'> & {
+type CostFunction<TEvent extends EventObject> = (path: AgentPath<TEvent>) => number;
+type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
     /**
      * The currently observed state.
      */
@@ -35,18 +37,50 @@ type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'pro
      * The previous plan.
      */
     previousPlan?: AgentPlan<TEvent>;
+    /**
+     * The total cost of the path to the goal state.
+     */
+    costFunction?: CostFunction<TEvent>;
+    /**
+     * The maximum number of attempts to generate a plan.
+     * Defaults to 2.
+     */
+    maxAttempts?: number;
+};
+type AgentStep<TEvent extends EventObject> = {
+    /** The event to take */
+    event: TEvent;
+    /** The next expected state after taking the event */
+    state: ObservedState | undefined;
+};
+type AgentPath<TEvent extends EventObject> = {
+    /** The expected ending state of the path */
+    state: ObservedState | undefined;
+    /** The steps to reach the ending state */
+    steps: Array<AgentStep<TEvent>>;
+    weight?: number;
 };
 type AgentPlan<TEvent extends EventObject> = {
+    /**
+     * The planner used to generate the plan
+     */
+    planner: string;
     goal: string;
-    state: ObservedState;
-    content?: string;
     /**
-     * Executes the plan based on the given `state` and resolves with
-     * a potential next `event` to trigger to achieve the `goal`.
+     * The ending state of the plan.
+     */
+    goalState: ObservedState | undefined;
+    /**
+     * The next event that the agent decided needs to occur to achieve the `goal`.
+     *
+     * This next event is chosen from the
      */
-    execute: (state: ObservedState) => Promise<TEvent | undefined>;
     nextEvent: TEvent | undefined;
-    sessionId: string;
+    /**
+     * The paths that the agent can take to achieve the goal.
+     */
+    paths: AgentPath<TEvent>[];
+    episodeId: string;
     timestamp: number;
 };
 interface TransitionData {
@@ -86,32 +120,34 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
     plans?: AgentPlan<TEvents>[];
 }) => string;
 type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
-type AgentDecideOptions = {
+type AgentDecideOptions<T extends AnyAgent> = {
     goal: string;
     model?: LanguageModel;
-    context?: any;
     state: ObservedState;
-    machine: AnyStateMachine;
+    machine?: AnyStateMachine;
     execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<any>;
+    planner?: AgentPlanner<T>;
     events?: ZodEventMapping;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt' | 'messages'>;
+    /**
+     * The maximum number of times the agent will attempt to make a decision.
+     * Defaults to 2.
+     */
+    maxAttempts?: number;
+} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 interface AgentFeedback {
     goal?: string;
     observationId?: string;
     /**
      * The message correlation that the feedback is relevant for
      */
-    correlationId?: string;
     attributes: Record<string, any>;
     reward: number;
     timestamp: number;
-    sessionId: string;
+    episodeId: string;
 }
 interface AgentFeedbackInput {
     goal?: string;
     observationId?: string;
-    correlationId?: string;
     attributes?: Record<string, any>;
     timestamp?: number;
     reward?: number;
@@ -125,10 +161,48 @@ type AgentMessage = CoreMessage & {
      */
     responseId?: string;
     result?: GenerateTextResult<any>;
-    sessionId: string;
-    correlationId: string;
-    parentCorrelationId?: string;
+    episodeId: string;
+};
+type JSONObject = {
+    [key: string]: JSONValue;
 };
+type JSONArray = JSONValue[];
+type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+type LanguageModelV1ProviderMetadata = Record<string, Record<string, JSONValue>>;
+interface LanguageModelV1TextPart {
+    type: 'text';
+    /**
+  The text content.
+     */
+    text: string;
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: LanguageModelV1ProviderMetadata;
+}
+interface LanguageModelV1ToolCallPart {
+    type: 'tool-call';
+    /**
+  ID of the tool call. This ID is used to match the tool call with the tool result.
+   */
+    toolCallId: string;
+    /**
+  Name of the tool that is being called.
+   */
+    toolName: string;
+    /**
+  Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+     */
+    args: unknown;
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: LanguageModelV1ProviderMetadata;
+}
 type AgentMessageInput = CoreMessage & {
     timestamp?: number;
     id?: string;
@@ -137,23 +211,21 @@ type AgentMessageInput = CoreMessage & {
      * which message this message is responding to, if any.
      */
     responseId?: string;
-    correlationId?: string;
-    parentCorrelationId?: string;
     result?: GenerateTextResult<any>;
 };
-interface AgentObservation<TActor extends AnyActorRef> {
+interface AgentObservation<TActor extends ActorRefLike> {
     id: string;
     prevState: SnapshotFrom<TActor> | undefined;
-    event: EventFrom<TActor>;
+    event: EventFrom<TActor> | undefined;
     state: SnapshotFrom<TActor>;
     machineHash: string | undefined;
-    sessionId: string;
+    episodeId: string;
     timestamp: number;
 }
 interface AgentObservationInput {
     id?: string;
-    prevState: ObservedState | undefined;
-    event: AnyEventObject;
+    prevState?: ObservedState;
+    event?: AnyEventObject;
     state: ObservedState;
     machine?: AnyStateMachine;
     timestamp?: number;
@@ -161,7 +233,7 @@ interface AgentObservationInput {
 type AgentDecisionInput = {
     goal: string;
     model?: LanguageModel;
-    context?: any;
+    context?: Record<string, any>;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<AgentPlan<TEvents> | undefined, AgentDecisionInput | string>;
 type AgentEmitted<TEvents extends EventObject> = {
@@ -199,7 +271,83 @@ type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
 type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
     [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
-type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
+type AnyAgent = Agent<any, any, any, any>;
+type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
+type CommonTextOptions = {
+    prompt: FromAgent<string>;
+    model?: LanguageModel;
+    context?: Record<string, any>;
+    messages?: FromAgent<CoreMessage[]>;
+    template?: PromptTemplate<any>;
+};
+type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
+type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
+interface ObservedState {
+    /**
+     * The current state value of the state machine, e.g.
+     * `"loading"` or `"processing"` or `"ready"`
+     */
+    value: StateValue;
+    /**
+     * Additional contextual data related to the current state
+     */
+    context?: Record<string, unknown>;
+}
+type ObservedStateFrom<TActor extends ActorRefLike> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
+type AgentMemoryContext = {
+    observations: AgentObservation<any>[];
+    messages: AgentMessage[];
+    plans: AgentPlan<any>[];
+    feedback: AgentFeedback[];
+};
+interface AgentLongTermMemory {
+    get<K extends keyof AgentMemoryContext>(key: K): Promise<AgentMemoryContext[K]>;
+    append<K extends keyof AgentMemoryContext>(key: K, item: AgentMemoryContext[K][0]): Promise<void>;
+    set<K extends keyof AgentMemoryContext>(key: K, items: AgentMemoryContext[K]): Promise<void>;
+}
+type Compute<A extends any> = {
+    [K in keyof A]: A[K];
+} & unknown;
+
+declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ id, description: description, model, events, context, planner, logic, }: {
+    /**
+     * The unique identifier for the agent.
+     *
+     * This should be the same across all sessions of a specific agent, as it can be
+     * used to retrieve memory for previous episodes of this agent.
+     *
+     * @example
+     * ```ts
+     * const agent = createAgent({
+     *  id: 'recipe-assistant',
+     *  // ...
+     * });
+     * ```
+     */
+    id?: string;
+    /**
+     * A description of the role of the agent
+     */
+    description?: string;
+    /**
+     * Events that the agent can cause (send) in an environment
+     * that the agent knows about.
+     */
+    events: TEventSchemas;
+    context?: TContextSchema;
+    planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
+    stringify?: typeof JSON.stringify;
+    /**
+     * A function that retrieves the agent's long term memory
+     */
+    getMemory?: (agent: Agent<TContextSchema, TEventSchemas>) => AgentLongTermMemory;
+    /**
+     * Agent logic
+     */
+    logic?: AgentLogic<TEvents>;
+    model: LanguageModel;
+} & GenerateTextOptions): Agent<TContextSchema, TEventSchemas>;
+declare class Agent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>> extends Actor<AgentLogic<TEvents>> {
     /**
      * The name of the agent. All agents with the same name are related and
      * able to share experiences (observations, feedback) with each other.
@@ -208,68 +356,97 @@ type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEve
     /**
      * The unique identifier for the agent.
      */
-    id?: string;
+    episodeId: string;
     description?: string;
-    events: ZodEventMapping;
+    events: TEventSchemas;
+    context?: TContextSchema;
+    planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
     types: {
         events: TEvents;
         context: Compute<TContext>;
     };
     model: LanguageModel;
-    defaultOptions: GenerateTextOptions;
     memory: AgentLongTermMemory | undefined;
-    /**
-     * The adapter used to perform LLM actions such as
-     * `.generateText(…)` and `.streamText(…)`.
-     *
-     * Defaults to the Vercel AI SDK.
-     */
-    adapter: AIAdapter;
-    /**
-     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
-     *
-     * - The `goal` for the agent to achieve
-     * - The observed current `state`
-     * - The `machine` (e.g. a state machine) that specifies what can happen next
-     * - Additional `context`
-     */
-    decide: (options: AgentDecideOptions) => Promise<AgentPlan<TEvents> | undefined>;
-    generateText: (options: AgentGenerateTextOptions) => Promise<AgentGenerateTextResult>;
-    streamText: (options: AgentStreamTextOptions) => Promise<AgentStreamTextResult>;
-    addObservation: (observationInput: AgentObservationInput) => AgentObservation<any>;
-    addMessage: (messageInput: AgentMessageInput) => AgentMessage;
-    addFeedback: (feedbackInput: AgentFeedbackInput) => AgentFeedback;
-    addPlan: (plan: AgentPlan<TEvents>) => void;
+    defaultOptions: AgentDecideOptions<AnyAgent> | undefined;
+    constructor({ logic, id, name, description, model, events, context, planner, }: {
+        logic: AgentLogic<TEvents>;
+        id?: string;
+        name?: string;
+        description?: string;
+        model: GenerateTextOptions['model'];
+        events: TEventSchemas;
+        context?: TContextSchema;
+        planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
+    });
     /**
      * Called whenever the agent (LLM assistant) receives or sends a message.
      */
-    onMessage: (callback: (message: AgentMessage) => void) => void;
-    /**
-     * Selects agent data from its context.
-     *
-     * @deprecated Select from `agent.getSnapshot().context` directly or:
-     * - `agent.getMessages()`
-     * - `agent.getObservations()`
-     * - `agent.getFeedback()`
-     * - `agent.getPlans()`
-     */
-    select: <T>(selector: (context: AgentMemoryContext) => T) => T;
+    onMessage(fn: (message: AgentMessage) => void): Subscription;
     /**
      * Retrieves messages from the agent's short-term (local) memory.
      */
-    getMessages: () => AgentMessage[];
+    addMessage(messageInput: AgentMessageInput): {
+        id: string;
+        timestamp: number;
+        episodeId: string;
+        role: "assistant";
+        content: ai.AssistantContent;
+        experimental_providerMetadata?: ai.ProviderMetadata;
+        responseId?: string;
+        result?: ai.GenerateTextResult<any>;
+    } | {
+        id: string;
+        timestamp: number;
+        episodeId: string;
+        role: "tool";
+        content: ai.ToolContent;
+        experimental_providerMetadata?: ai.ProviderMetadata;
+        responseId?: string;
+        result?: ai.GenerateTextResult<any>;
+    } | {
+        id: string;
+        timestamp: number;
+        episodeId: string;
+        role: "system";
+        content: string;
+        experimental_providerMetadata?: ai.ProviderMetadata;
+        responseId?: string;
+        result?: ai.GenerateTextResult<any>;
+    } | {
+        id: string;
+        timestamp: number;
+        episodeId: string;
+        role: "user";
+        content: ai.UserContent;
+        experimental_providerMetadata?: ai.ProviderMetadata;
+        responseId?: string;
+        result?: ai.GenerateTextResult<any>;
+    };
+    getMessages(): AgentMessage[];
+    addFeedback(feedbackInput: AgentFeedbackInput): {
+        attributes: {
+            [x: string]: any;
+        };
+        reward: number;
+        timestamp: number;
+        episodeId: string;
+        goal?: string;
+        observationId?: string;
+    };
     /**
-     * Retrieves observations from the agent's short-term (local) memory.
+     * Retrieves feedback from the agent's short-term (local) memory.
      */
-    getObservations: () => AgentObservation<Agent<TContext, TEvents>>[];
+    getFeedback(): AgentFeedback[];
+    addObservation(observationInput: AgentObservationInput): AgentObservation<any>;
     /**
-     * Retrieves feedback from the agent's short-term (local) memory.
+     * Retrieves observations from the agent's short-term (local) memory.
      */
-    getFeedback: () => AgentFeedback[];
+    getObservations(): AgentObservation<any>[];
+    addPlan(plan: AgentPlan<TEvents>): void;
     /**
      * Retrieves strategies from the agent's short-term (local) memory.
      */
-    getPlans: () => AgentPlan<TEvents>[];
+    getPlans(): AgentPlan<any>[];
     /**
      * Interacts with this state machine actor by inspecting state transitions and storing them as observations.
      *
@@ -286,7 +463,7 @@ type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEve
      * actor.start();
      * ```
      */
-    interact<TActor extends AnyActorRef>(actorRef: TActor): Subscription;
+    interact<TActor extends ActorRefLike>(actorRef: TActor): Subscription;
     /**
      * Interacts with this state machine actor by:
      * 1. Inspecting state transitions and storing them as observations
@@ -314,115 +491,29 @@ type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEve
      * actor.start();
      * ```
      */
-    interact<TActor extends AnyActorRef>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
-};
-type AnyAgent = Agent<any, any>;
-type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
-type CommonTextOptions = {
-    prompt: FromAgent<string>;
-    model?: LanguageModel;
-    context?: Record<string, any>;
-    messages?: FromAgent<CoreMessage[]>;
-    template?: PromptTemplate<any>;
-    correlationId?: string;
-    parentCorrelationId?: string;
-};
-type TextResultMeta = {
-    correlationId: string;
-    parentCorrelationId?: string;
-};
-type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentGenerateTextResult = GenerateTextResult<any> & TextResultMeta;
-type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentStreamTextResult = StreamTextResult<any> & TextResultMeta;
-interface ObservedState {
+    interact<TActor extends ActorRefLike>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
+    observe<TActor extends ActorRefLike>(actorRef: TActor): Subscription;
+    wrap(modelToWrap: LanguageModelV1): LanguageModelV1;
     /**
-     * The current state value of the state machine, e.g.
-     * `"loading"` or `"processing"` or `"ready"`
-     */
-    value: StateValue;
-    /**
-     * Additional contextual data related to the current state
-     */
-    context: Record<string, unknown>;
-}
-type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
-type AgentMemoryContext = {
-    observations: AgentObservation<any>[];
-    messages: AgentMessage[];
-    plans: AgentPlan<any>[];
-    feedback: AgentFeedback[];
-};
-type AgentMemory = AppendOnlyStorage<AgentMemoryContext>;
-interface AppendOnlyStorage<T extends Record<string, any[]>> {
-    append<K extends keyof T>(sessionId: string, key: K, item: T[K][0]): Promise<void>;
-    getAll<K extends keyof T>(sessionId: string, key: K): Promise<T[K] | undefined>;
-}
-interface AgentLongTermMemory {
-    get<K extends keyof AgentMemoryContext>(key: K): Promise<AgentMemoryContext[K]>;
-    append<K extends keyof AgentMemoryContext>(key: K, item: AgentMemoryContext[K][0]): Promise<void>;
-    set<K extends keyof AgentMemoryContext>(key: K, items: AgentMemoryContext[K]): Promise<void>;
-}
-interface AIAdapter {
-    generateText: typeof generateText;
-    streamText: typeof streamText;
-}
-type Compute<A extends any> = {
-    [K in keyof A]: A[K];
-} & unknown;
-
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ name, description, model, events, context, planner, stringify, getMemory, logic, adapter, ...generateTextOptions }: {
-    /**
-     * The unique identifier for the agent.
-     *
-     * This should be the same across all sessions of a specific agent, as it can be
-     * used to retrieve memory for this agent.
+     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
      *
-     * @example
-     * ```ts
-     * const agent = createAgent({
-     *  id: 'recipe-assistant',
-     *  // ...
-     * });
-     * ```
-     */
-    id?: string;
-    /**
-     * The name of the agent
-     */
-    name?: string;
-    /**
-     * A description of the role of the agent
-     */
-    description?: string;
-    /**
-     * Events that the agent can cause (send) in an environment
-     * that the agent knows about.
-     */
-    events: TEventSchemas;
-    context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContext, TEvents>>;
-    stringify?: typeof JSON.stringify;
-    /**
-     * A function that retrieves the agent's long term memory
-     */
-    getMemory?: (agent: Agent<TContext, TEvents>) => AgentLongTermMemory;
-    /**
-     * Agent logic
+     * - The `goal` for the agent to achieve
+     * - The observed current `state`
+     * - The `machine` (e.g. a state machine) that specifies what can happen next
+     * - Additional `context`
      */
-    logic?: AgentLogic<TEvents>;
-    adapter?: AIAdapter;
-} & GenerateTextOptions): Agent<TContext, TEvents>;
+    decide(opts: AgentDecideOptions<this>): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
+}
 
-declare function fromTextStream<T extends AnyAgent>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
+declare function fromTextStream<T extends AnyAgent>(agent: T, options?: AgentStreamTextOptions): ObservableActorLogic<{
     textDelta: string;
 }, Omit<AgentStreamTextOptions, 'context'> & {
     context?: AgentStreamTextOptions['context'];
 }>;
-declare function fromText<T extends AnyAgent>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
+declare function fromText<T extends AnyAgent>(agent: T, options?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
     context?: AgentGenerateTextOptions['context'];
 }>;
 
 declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
 
-export { type AIAdapter, type Agent, type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentGenerateTextResult, type AgentLogic, type AgentLongTermMemory, type AgentMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, type AgentStreamTextResult, type AnyAgent, type AppendOnlyStorage, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TextResultMeta, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };
+export { type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentLogic, type AgentLongTermMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPath, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStep, type AgentStreamTextOptions, type AnyAgent, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type CostFunction, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type LanguageModelV1TextPart, type LanguageModelV1ToolCallPart, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };