Plan Class

Send prompt-bound Plan activities; the application owns ordering and concurrency.

A Plan is bound to a single conversation and a single originating prompt (reply_to_id), and it does not hold a mutable conversation reference or a hidden live session object. The runtime client is injected separately and is scoped to the conversation's service URL before use.

Targeted Plan scenarios are not supported. Plan activities use ordinary create routing.

Preview API. Diagnostic: ExperimentalTeamsPlan

Constructor

Plan(*, conversationId: str, replyToId: str, replyChain: PlanReplyChain | None = None, **options: Unpack[PlanOptions])

Keyword-Only Parameters

Name Description
conversationId
Required
replyToId
Required
replyChain
Default value: None

Methods

complete

Complete the Plan and send the final response.

completion

Build a fresh completion message for this Plan's prompt without sending or emitting events.

Emit it last on a stream targeting the same conversation, then close the stream.

error

Signal an error state for the active Plan.

start

Start a new Plan for the bound prompt.

stop

Stop the active Plan for the bound prompt.

update

Send a continuing Plan update for the current prompt.

complete

Complete the Plan and send the final response.

async complete(message: str | MessageActivityInput) -> SentActivity

Parameters

Name Description
message
Required

Final response text or a full MessageActivityInput payload. If the payload already contains a planInfo entity, it must be a complete operation; other plan operations are rejected.

Returns

Type Description

The SentActivity returned by the underlying conversation API call.

Exceptions

Type Description

If the supplied message includes any PlanInfoEntity whose plan_type is not "complete"

Any API/network exceptions raised by the underlying conversation client.

completion

Build a fresh completion message for this Plan's prompt without sending or emitting events.

Emit it last on a stream targeting the same conversation, then close the stream.

completion() -> MessageActivityInput

error

Signal an error state for the active Plan.

async error() -> None

Returns

Type Description

None. This sends a planInfo entity with planType of "error" and emits sent after success.

Exceptions

Type Description
Any API/network exceptions raised by the underlying conversation client.

start

Start a new Plan for the bound prompt.

async start(steps: Sequence[Step]) -> None

Parameters

Name Description
steps
Required

Ordered step list to include in the start payload.

Returns

Type Description

None. The send result is exposed via the sent event.

Exceptions

Type Description
Any API/network exceptions raised by the underlying conversation client.

stop

Stop the active Plan for the bound prompt.

async stop() -> None

Returns

Type Description

None. This sends a planInfo entity with planType of "stop" and emits sent after success.

Exceptions

Type Description
Any API/network exceptions raised by the underlying conversation client.

update

Send a continuing Plan update for the current prompt.

async update(steps: Sequence[Step]) -> None

Parameters

Name Description
steps
Required

New or updated plan steps describing the current state.

Returns

Type Description

None. This method emits the sent event on a successful response.

Exceptions

Type Description
Any API/network exceptions raised by the underlying conversation client.

Attributes

events

Emit lifecycle notifications for successfully sent Plan activities.

The emitter exposes a single event named "sent". The payload is the SentActivity returned from the API after the activity is created. The event fires once the underlying create request succeeds and before the method returns.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_config: ClassVar[ConfigDict] = {'alias_generator': AliasGenerator(alias=None, validation_alias=<staticmethod(<function CustomBaseModel.validation_alias_generator>)>, serialization_alias=<staticmethod(<function CustomBaseModel.serialization_alias_generator>)>), 'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'serialize_by_alias': True, 'validate_by_alias': True}

conversation_id

conversation_id: str

reply_chain

reply_chain: PlanReplyChain | None

reply_to_id

reply_to_id: str