RFC: Topic Endpoint

[Swiftyos]

Feature name	Interface Specification Enhancement
Author(s)	swiftyos (craigswift13@gmail.com)
Updated	2023-11-02

Summary

Current agent interaction mechanisms are primarily task-oriented. They lack the conversational fluidity and persistent memory capabilities desired for more intuitive and less repetitive user engagements. This proposal introduces the "Topic Endpoint" concept to bridge this gap, facilitating more natural, chat-based interactions and enabling memory persistence across different tasks.

Motivation

The primary motivation is to enhance user experience by aligning agent interactions more closely with user expectations. Users anticipate a conversational engagement and a memory retention feature that saves them from providing the same information repetitively. By ensuring a persistent memory and a more natural interaction model, we aim to expedite task execution and enrich user-agent interaction.

Agent Builders Benefit

• Multi-task Persistent Memory: Enable agents to remember context and information across multiple tasks, reducing the need for users to repeat information.
• Natural Interactions: Allow users to interact with agents in a more conversational manner, without being bound strictly to task-oriented dialogues.
• Ease of Development: Simplify the development process by not requiring overriding of the existing task concept to achieve the desired interaction model.

Design Proposal

This proposal recommends introducing new abstract entities and refining the interactions among existing entities within the system. Here are the key entities from an abstract perspective:

• Topic: A persistent long-term concept, encapsulating a set of related tasks and interactions.
• Interaction: A chat-like messaging mechanism allowing for back-and-forth communication with the topic, thus facilitating a more natural dialogue.
• Task: Represents a task with a specific goal. Tasks are grouped under topics and can access shared memory within the topic.
• Step: Denotes a specific step within a task, guiding the task towards its goal.
• Artifact: Signifies a persistent resource space owned by an agent, wherein data relevant to a topic is stored and managed.

Interaction Flow

1. Topic Initiation: A user initiates a topic, setting the stage for a set of related tasks.
2. Interaction: The user engages in a chat-based interaction within the topic, providing necessary information and context.
3. Task Execution: Based on the interaction, tasks are created and executed in sequence or parallel, as appropriate.
4. Step Processing: Each task is broken down into steps, ensuring structured progress towards the goal.
5. Artifact Management: Artifacts are updated and managed throughout the interaction, retaining essential information for future reference.

sequenceDiagram
title: Interaction Flow among User, Topic, Task, and Step
participant User
participant Topic
participant Task
participant Step

User -> Topic: Initiate Topic
loop Interaction Loop
    User -> Topic: Chat-based Interaction
    Topic -> Task: Derive Task from Interaction
        loop Step Execution Loop
            User -> Step: Execute Step
            Step -> Task: Update Task State
            Step -> Step: Create Artifact
            Step -> Step: Update Step State
        end
    Topic -> User: Provide Task Completion Feedback
end

Loading

Detailed Design

The proposed transition in endpoint structure is poised to encapsulate tasks within higher-level entities known as topics, shifting from the existing endpoint /ap/v1/agent/tasks/{task_id} to a more organized format /ap/v2/topics/{topic_id}/tasks/{task_id}. Additionally, a new endpoint /ap/v2/topics/{topic_id}/interactions/{interaction_id} will be added to handle interactions within those topics in a more chat like manner. The agent verb is being dropped as it adds no value. This new structure aims to facilitate a more intuitive and organized approach to handling user interactions and task management.

Endpoint Specifications

Topics

1. Create a New Topic:

   • Endpoint: /ap/v2/topics
   • POST Method:
     • OperationId: createTopic
     • Summary: Create a new topic.
     • RequestBody:
       • Content: application/json
     • Responses:
       • '201': Successfully created a new topic.
       • '400': Bad request.

2. List Topics:

   • Endpoint: /ap/v2/topics
   • GET Method:
     • OperationId: listTopics
     • Summary: Retrieve a list of all topics.
     • Responses:
       • '200': Successfully retrieved list of topics.

3. Get a Specific Topic:

   • Endpoint: /ap/v2/topics/{topic_id}
   • GET Method:
     • OperationId: getTopic
     • Summary: Retrieve details of a specified topic.
     • Parameters:
       • topic_id
     • Responses:
       • '200': Successfully retrieved topic details.
       • '404': Topic not found.

Interactions

1. Create a New Interaction:

   • Endpoint: /ap/v2/topics/{topic_id}/interactions
   • POST Method:
     • OperationId: createInteraction
     • Summary: Create a new interaction within a specified topic.
     • Parameters:
       • topic_id
     • RequestBody:
       • Content: application/json
     • Responses:
       • '201': Successfully created a new interaction.
       • '400': Bad request.

2. List Interactions in a Topic:

   • Endpoint: /ap/v2/topics/{topic_id}/interactions
   • GET Method:
     • OperationId: listTopicInteractions
     • Summary: Retrieve a list of interactions for a specified topic.
     • Parameters:
       • topic_id
     • Responses:
       • '200': Successfully retrieved list of interactions.

3. Get a Specific Interaction in a Topic:

   • Endpoint: /ap/v2/topics/{topic_id}/interactions/{interaction_id}
   • GET Method:
     • OperationId: getTopicInteraction
     • Summary: Retrieve details of a specified interaction within a topic.
     • Parameters:
       • topic_id, interaction_id
     • Responses:
       • '200': Successfully retrieved interaction details.
       • '404': Interaction not found.

The design of these endpoints follows a RESTful approach, ensuring a clear and organized way to interact with topics, interactions, and tasks within the new v2 structure. Each endpoint provides specific functionalities, enabling clients to manage and retrieve information efficiently.

Certainly! Here are the requested sections tailored to fit the context of your proposal on transitioning to a new endpoint structure:

Alternatives Considered

The principal alternative deliberated is retaining the current endpoint structure /ap/v1/agent/tasks/{task_id}/steps without migrating to the hierarchical structure proposed. However, this alternative falls short in addressing the emerging need for a shared memory framework and the ability to handle chat-like interactions which are imperative for spawning tasks in a more intuitive and natural manner. The current flat structure may continue to pose challenges in efficiently managing and retrieving data as the system scales.

Note on Plugin Entities

It's important to emphasize that adding plugin entities to the interface is beyond the scope of this proposal. The focus here is on enhancing the clarity of the existing interface specification and addressing issues related to entity ownership and state changes.

Compatibility

The design proposal is crafted with backward compatibility in mind to ensure a smooth transition for existing systems. It's crucial to create comprehensive documentation and guidelines to aid in the implementation of the updated endpoint structure. Ensuring compatibility with other integral components of the system, such as SDK and Client SDK, is also paramount. Adequate checks and balances need to be put in place to ascertain that the transition to the new endpoint structure /ap/v2/topics/{topic_id}/tasks/{task_id} and /ap/v2/topics/{topic_id}/interactions/{interaction_id}does not disrupt the existing functionalities while paving the way for enhanced user interactions and data organization.

[Swiftyos]

Maybe we should be calling this Threads now :)

[Pwuts]

Related: #44

[ntindle]

Can you attend a meeting the Agent protocol meeting on the 12th to discuss this?