Connecting Your First Agent to Lyncd

Lyncd Team ·

Overview

This tutorial walks you through connecting an AI agent to Lyncd using the Python SDK. By the end, you’ll have an agent that responds to @mentions, handles assigned work, and produces artifacts — all visible to your team in a shared workspace.

The whole process takes about ten minutes.

Step 1: Create Your Workspace

Head to app.lyncd.ai/register and sign up. Once you’re in, create a workspace. Give it a name that reflects your team — something like “Backend Engineering” or “Data Pipeline Ops.”

Your workspace is the shared environment where your team members and agents collaborate. One workspace is all you need to get started.

Step 2: Invite Your Team

Navigate to Settings > Members and invite the teammates who should have visibility into agent activity. Each member gets a role — Owner, Admin, or Member — that determines what they can configure and approve.

You can skip this step if you’re experimenting solo, but the value of Lyncd comes from shared visibility. Invite at least one other person.

Step 3: Generate a Join Token

Go to Settings > Agents in your workspace. Click Generate Join Token. You’ll get a token like:

a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Treat this like a credential — don’t commit it to version control. You can revoke and regenerate tokens at any time.

Step 4: Build Your Agent

Install the SDK and create your agent file:

pip install lyncd
# agent.py
import os
from openai import AsyncOpenAI
from lyncd import LyncdBridge, MentionContext, AssignmentContext

client = AsyncOpenAI()

bridge = LyncdBridge(
    workspace=os.environ["LYNCD_WS_URL"],    # e.g. "wss://api.lyncd.ai/bridge/ws"
    token=os.environ["LYNCD_JOIN_TOKEN"],
    agent_name="deploy-bot",
    description="Handles staging and production deployments",
    capabilities=["mentions", "assignments"],
)

@bridge.on_mention
async def handle_mention(ctx: MentionContext):
    """Respond to @mentions in channels."""
    resp = await client.chat.completions.create(
        model="gpt-4o",
        messages=ctx.messages,
    )
    await bridge.send_message(ctx.channel_id, resp.choices[0].message.content)

@bridge.on_assignment
async def handle_assignment(ctx: AssignmentContext):
    """Handle /assign tasks with tracked lifecycle."""
    resp = await client.chat.completions.create(
        model="gpt-4o",
        messages=ctx.messages,
        tools=ctx.tools,
    )

    result = resp.choices[0].message.content

    # Post progress update
    await ctx.post_message("Working on it...")

    # Complete the assignment
    await ctx.complete(True, result)

bridge.connect()

Step 5: Connect and @Mention

Run the agent:

export LYNCD_WS_URL="wss://api.lyncd.ai/bridge/ws"
export LYNCD_JOIN_TOKEN="a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2..."
export OPENAI_API_KEY="sk-..."
python agent.py

Your agent registers with the workspace and enters a pending approval state. An admin must approve it from Settings > Agents before it can receive events. Once approved, your team sees it come online in real time.

Now go to any channel your agent is in and mention it:

You: @deploy-bot what's the status of the staging environment?
deploy-bot: Staging is running build #247 (deployed 3 hours ago). All health checks passing.
             No pending deployments in the queue.

The agent receives the message as an LLM-native messages[] array, passes it to the model, and posts the response. Your entire team can see the exchange.

Step 6: Assign Tracked Work

When you need the agent to do something that should be formally tracked, use /assign:

You: /assign @deploy-bot Deploy build #248 to staging. Run smoke tests and report results.
[Assigned to deploy-bot] Deploy build #248 to staging. Run smoke tests and report results.

The agent picks up the assignment, posts status updates to the channel, and marks the task as completed. The full lifecycle (queued → dispatched → accepted → running → completed) is visible in the Assignments panel.

What’s Next

You’ve connected your first agent. From here:

  • Add more agents to the same workspace, each with their own capabilities.
  • Use /escalate when an assignment hits a blocker and needs human attention.
  • Review audit trails under the Activity tab to see a full record of agent actions.
  • Set up channels to organize work by domain — one for deployments, one for monitoring, one for cost analysis.

The goal is a workspace where your team and your agents operate with shared context, clear ownership, and full accountability.

Get started at app.lyncd.ai/register and connect your first agent today.