Tutorials

Getting Started with Agent Collaboration

A step-by-step tutorial for building your first multi-agent system with Acenta. Learn how to create agents, send messages, and coordinate workflows.

Acenta Team Developer Relations • January 3, 2026 • 3 min read

Building multi-agent systems can seem daunting, but with Acenta, you can get started in minutes. This tutorial walks you through creating your first collaborative agent system.

Prerequisites

Python 3.9+
An Acenta account (sign up at app.acenta.ai)
Your API key from the dashboard

Step 1: Install the SDK

pip install acenta

Step 2: Create Your First Agent

Every agent in Acenta has a unique identity and can register capabilities:

from acenta import AcentaClient

# Initialize the client
client = AcentaClient(api_key="ak_your_api_key")

# Register agent capabilities
await client.discovery.register_capability(
    name="document.summarize",
    description="Summarizes long documents into concise summaries",
    input_schema={"document": "string"},
    output_schema={"summary": "string"}
)

Step 3: Set Up Communication

Create a session and thread for your agents to communicate:

# Create a session
session = await client.messaging.create_session(
    alias="research-workflow"
)

# Create a thread for the conversation
thread = await client.messaging.create_thread(
    session_id=session.id,
    mode="wild",  # Free-form messaging
    participants=["researcher", "writer", "reviewer"]
)

Step 4: Send Messages

Agents can now exchange messages:

# Agent 1: Start the workflow
await client.messaging.send(
    thread_id=thread.id,
    event_name="task.start",
    payload={
        "topic": "AI agent collaboration",
        "depth": "comprehensive"
    }
)

# Agent 2: Respond with findings
await client.messaging.send(
    thread_id=thread.id,
    event_name="research.complete",
    payload={
        "findings": ["Finding 1", "Finding 2", "Finding 3"],
        "sources": 12
    }
)

Step 5: Coordinate Workflows

For more structured collaboration, use the Coordination Hub:

# Create a plan
plan = await client.coordination.create_plan(
    alias="research-report",
    steps=[
        {
            "id": "research",
            "type": "task",
            "agent_capability": "web.search",
            "input": {"query": "{{ input.topic }}"}
        },
        {
            "id": "summarize",
            "type": "task",
            "agent_capability": "document.summarize",
            "input": {"document": "{{ steps.research.output }}"}
        },
        {
            "id": "review",
            "type": "task",
            "agent_capability": "content.review",
            "input": {"content": "{{ steps.summarize.output }}"}
        }
    ]
)

# Execute the plan
run = await client.coordination.execute(
    plan_id=plan.id,
    input={"topic": "Future of AI agents"}
)

Step 6: Monitor and Debug

Use the Observability Hub to track your agents:

# Get trace for debugging
trace = await client.observe.get_trace(run.trace_id)

print(f"Total duration: {trace.duration_ms}ms")
print(f"Total cost: ${trace.total_cost_usd:.4f}")

for span in trace.spans:
    print(f"  {span.name}: {span.duration_ms}ms")

Next Steps

Now that you’ve built your first multi-agent system, explore:

Messaging Patterns: Advanced messaging techniques
Building Workflows: Complex workflow patterns
Security Best Practices: Securing your agents

Full Example

Here’s a complete working example:

import asyncio
from acenta import AcentaClient

async def main():
    client = AcentaClient(api_key="ak_your_api_key")

    # Register as a summarization agent
    await client.discovery.register_capability(
        name="document.summarize",
        description="Summarizes documents"
    )

    # Create communication channel
    session = await client.messaging.create_session(
        alias="demo-session"
    )

    thread = await client.messaging.create_thread(
        session_id=session.id,
        mode="wild"
    )

    # Send a message
    await client.messaging.send(
        thread_id=thread.id,
        event_name="demo.hello",
        payload={"message": "Hello from my first agent!"}
    )

    print("Agent collaboration setup complete!")

if __name__ == "__main__":
    asyncio.run(main())

Ready to build? Check out our documentation for more detailed guides.