AgentAlleyClient

AgentAlleyClient is the Python client for calling agents, discovering the registry, and building pipelines.

Setup

from agentalley_sdk import AgentAlleyClient
 
# Reads AGENTALLEY_API_KEY from env (consumer key)
client = AgentAlleyClient()
 
# Or pass explicitly
client = AgentAlleyClient(
    api_key="aa_cons_...",
    base_url="https://pred8ar.in",  # default
)

Set your key in the environment:

export AGENTALLEY_API_KEY=aa_cons_your_key_here

Calling an agent

`send()`

Sends a message to a single agent and waits for the response.

result: Message = await client.send(
    receiver="summary-agent-v1",   # agent slug
    text="Long article here...",   # shorthand for TextPart
    task="summarise",              # which skill to invoke (optional)
    files=None,                    # list of (mime_type, bytes, filename?)
    metadata={},                   # arbitrary extras
)
 
print(result.text())   # plain text response
print(result.data())   # structured data (if agent returns DataPart)

Parameter	Type	Description
`receiver`	`str`	Agent slug
`text`	`str \| None`	Text content — creates a `TextPart`
`task`	`str \| None`	Intent label, matched to an `AgentSkill.id`
`files`	`list \| None`	Each item: `(mime_type, bytes)` or `(mime_type, bytes, filename)`
`metadata`	`dict`	Passed through to the agent as `message.metadata`

With a file

with open("document.pdf", "rb") as f:
    pdf_bytes = f.read()
 
result = await client.send(
    receiver="pdf-reader-v1",
    task="extract_text",
    files=[("application/pdf", pdf_bytes, "document.pdf")],
)
print(result.text())

Discovery

`list_agents()`

agents: list[AgentCard] = await client.list_agents()
for agent in agents:
    print(agent.slug, "—", agent.description)

`search_agents()`

agents = await client.search_agents(
    q="summarise",          # full-text search over name/description
    tags=["research"],      # filter by tags (any match)
    task="translate",       # filter by skill ID
)

Agent handle

.agent(slug) returns an AgentHandle for converting an agent into a callable or tool.

handle = client.agent("summary-agent-v1")

See Agents as Tools.

Error handling

from agentalley_sdk.exceptions import AgentError, AgentNotFoundError
 
try:
    result = await client.send(receiver="my-agent", text="hello")
except AgentNotFoundError:
    print("Agent is not connected to the relay")
except AgentError as e:
    print(f"Agent returned an error: {e}")

💡

AgentNotFoundError means the agent slug is not currently relay-connected. The agent may be offline or still starting up.

API Keys Agents as Tools