ichatbio-sdk 0.1.5

A framework which allows AI agents to interact with iChatBio using the A2A protocol.

iChatBio SDK

The iChatBio SDK is designed to aid in the development of agents that can communicate with iChatBio. The SDK adds a layer of abstraction over the A2A protocol, hiding the complexities of A2A while exposing iChatBio-specific capabilities. Because agents designed with the iChatBio SDK make use of A2A, they are also able to communicate with other A2A agents, though without access to services (e.g., strict data models, special messages types, and shared persistent storage) enabled by the iChatBio ecosystem.

Getting started

See examples for a reference agent implementation. A standalone example agent is available here.

Like A2A, iChatBio agents must define an agent card. Here's an example card:

from ichatbio.types import AgentCard, AgentEntrypoint

card = AgentCard(
    name="Friendly Agent",
    description="Responds in a friendly manner.",
    icon="https://example.com/icon.png",
    entrypoints=[
        AgentEntrypoint(
            id="chat",
            description="Generates a friendly reply.",
            parameters=ChatParameters  # Defined below
        )
    ]
)

The card must include one or more entrypoints. Entrypoints define the types of interactions that are possible between iChatBio and the agent. Each entrypoint can optionally define a set of parameters, which allow iChatBio to provide structured information to the agent. This structure has a number of advantages:

• Agents can directly access parameters without the unreliable overhead of natural language processing
• Agents with strict parameter sets can only be used when the required parameters are supplied

Here's the parameter model referenced in the entrypoint above:

from pydantic import BaseModel, PastDate


class ChatParameters(BaseModel):
    birthday: PastDate

By using Pydantic's PastDate class, the birthday must both be a valid date and also be a date in the past. With these constraints, the agent does not need to worry about receiving invalid parameter values and subsequent error handling.

Here's an agent that implements the "chat" entrypoint:

from typing import Optional, override, AsyncGenerator
from datetime import date
from pydantic import BaseModel

from ichatbio.agent import IChatBioAgent
from ichatbio.types import AgentCard, Message, TextMessage, ProcessMessage, ArtifactMessage


class FriendlyAgent(IChatBioAgent):
    @override
    def get_agent_card(self) -> AgentCard:
        return card  # The AgentCard we defined earlier

    @override
    async def run(self, request: str, entrypoint: str, params: Optional[BaseModel]) -> AsyncGenerator[
        None, Message]:
        if entrypoint != "chat":
            raise ValueError()  # This should never happen

        yield ProcessMessage(summary="Replying",
                             description="Generating a friendly reply")
        response = ...  # Query an LLM

        yield ProcessMessage(description="Response generated",
                             data={"response": response})

        happy_birthday = ChatParameters(params).birthday == date.today()
        if happy_birthday:
            yield ProcessMessage(description="Generating a birthday surprise")
            audio: bytes = ...  # Generate an audio version of the response
            yield ArtifactMessage(
                mimetype="audio/mpeg",
                description=f"An audio version of the response",
                content=audio)

        yield TextMessage(
            "I have generated a friendly response to the user's request. For their birthday, I also generated an audio version of the response."
            if happy_birthday else
            "I have generated a friendly response to the user's request.")

And here's a __main__.py to run the agent as an A2A web server:

from ichatbio.server import run_agent_server

if __name__ == "__main__":
    agent = FriendlyAgent()
    run_agent_server(agent, host="0.0.0.0", port=9999)

If all went well, you should be able to find your agent card at http://localhost:9999/.well-known/agent.json.

SDK Development

Requires Python 3.10 or higher.

Dependencies for the example agents are installed separately:

pip install .[example]

Funding

This work is funded by grants from the National Science Foundation (DBI 2027654) and the AT&T Foundation.