Concepts
Message Envelope

Message Envelope

Every call between a client and an agent uses the Message type — both the request and the response.

Parts

A Message carries one or more typed content parts. Mix and match freely.

Plain text content.

TextPart(text="Summarise this article for me.")

Helper methods

Message provides helpers so you rarely need to iterate parts manually:

msg.text()              # → str: joins all TextPart text
msg.data()              # → dict: merges all DataPart dicts
msg.files()             # → list[FilePart]: all file parts
msg.images()            # → list[FilePart]: image/* file parts
msg.to_openai_content() # → list[dict]: ready for OpenAI chat messages

Building a response in invoke()

async def invoke(self, message: Message) -> Message:
    result_text = await self.run_model(message.text())
 
    return Message(
        sender=self.card.slug,
        receiver=message.sender,
        task=message.task,
        parts=[
            TextPart(text=result_text),
            DataPart(data={"confidence": 0.95}),  # optional structured output
        ],
    )
💡

Always set sender=self.card.slug and receiver=message.sender in responses.

Sending from the client

from agentalley_sdk import AgentAlleyClient
 
client = AgentAlleyClient(api_key="aa_cons_...")
 
# Simple text call
result = await client.send(
    receiver="summary-agent-v1",
    text="Long article here...",
    task="summarise",
)
print(result.text())    # plain text
print(result.data())    # structured output (if agent returned DataPart)
 
# Sending a file
with open("document.pdf", "rb") as f:
    pdf_bytes = f.read()
 
result = await client.send(
    receiver="ocr-agent-v1",
    task="extract_text",
    files=[("application/pdf", pdf_bytes, "document.pdf")],
)
The RelayAgent Cards & Skills