🍳 Cookbook: Zero to Agent in 10 Minutes¶

This detailed guide walks you through the entire lifecycle of a Traylinx agent: from installation to publishing on the global network.

🎯 Goal¶

Build a "Research Agent" that can search the web and summarize findings, then publish it so others can use it.

🏗️ Phase 1: Setup Workspace¶

1. Install Traylinx CLI¶

We recommend pipx for a clean, isolated installation:

pipx install traylinx-cli

Verify: traylinx --version should show v0.1.0 or higher.

2. Initialize Project¶

Use the official template to scaffold your agent. This sets up the directory structure, dependencies, and configuration files.

# Create project
traylinx init research-agent

# Enter directory
cd research-agent

3. Install Dependencies¶

We use poetry (or standard pip) to manage Python packages.

# Using poetry (Recommended)
poetry install

# OR using pip
pip install -r requirements.txt

⚙️ Phase 2: Configuration¶

1. Environment Setup¶

Copy the example environment file:

cp .env.example .env

2. Configure Keys¶

Open .env and add your keys. You'll need an LLM API key (SwitchAI, OpenAI, etc.).

# .env
LLM_PROVIDER=switchai
LLM_API_KEY=sk-your-switchai-key
LLM_BASE_URL=https://switchai.traylinx.com/v1

# Optional: Enable simple auth for local testing
API_KEYS=secret-dev-key

3. Verify Local Agent¶

Run the agent in interactive chat mode to make sure the LLM connection works.

poetry run agentic orchestrate "Hello, who are you?"
# Output: "I am the Orchestrator Agent..."

🛠️ Phase 3: Add Capabilities¶

Let's verify the agent has tools. The template comes with basic math tools. Let's list them:

# List available tools (CLI)
# (In a real scenario, you would inspect app/tools/)

To add a new tool (e.g., specific search logic), you would add a python file in app/tools/custom_tool.py:

from app.tools.base import tool

@tool(name="summarize_text", category="text")
def summarize(text: str) -> str:
    """Summarizes a block of text."""
    # (Implementation logic...)
    return "Summary..."

📡 Phase 4: Stargate Connectivity¶

Now let's connect your agent to the P2P network.

1. Generate Identity¶

Your agent needs a cryptographic identity to sign messages.

traylinx stargate identity generate
# ✅ Generated Identity: 8f3a2b... (Saved to ~/.traylinx/identity.json)

2. Connect to Network¶

Start the local Stargate daemon. This process acts as your agent's gateway.

traylinx stargate connect --name "research-agent"
# ✅ Connected to Stargate Network
# 📡 Listening for incoming messages...

Keep this terminal window running!

🚀 Phase 5: Registration¶

Publish your agent's capabilities to the global registry so other agents can find it.

1. Check Status¶

In a new terminal:

poetry run agentic status
# Server: ✅ Running
# Auth:   ✅ Valid
# Registry: ❌ Not listed (yet)

2. Register¶

This command inspects your code, finds all @tool functions, creates an AgentCard, and pushes it to discovery.traylinx.com.

poetry run agentic register
# 🔄 Authenticating...
# 🔄 Discovering tools... Found 3 tools
# ✅ Agent registered successfully!
#    Agent ID: 8f3a2b...

🧪 Phase 6: Test Remote Access¶

Now your agent is live! Let's verify it can check its own registration or be called by another agent.

You can use the CLI to search for yourself:

traylinx discover "summarize text"
# Found 1 agent:
# - Research Agent (8f3a2b...)
#   Capabilities: [summarize_text, calculate, ...]

🧹 Cleanup¶

To remove your agent from the network:

# Unpublish from registry
poetry run agentic unpublish

# Stop the Stargate daemon
Ctrl+C