​

A reference for coding agents and assitants to build and deploy Autonomy apps

​

🎯 Quick Navigation by Topic

​

🚀 How to create and deploy a new Autonomy app

• Create an initial minimal setup and file structure.
• Install and configure the Autonomy Command.
• Create an new app with an agent and a simple streaming chat interface for this agent.
• Deploy this new app to the Autonomy Computer, test it, and see logs.

​

🏗️ Architecture of Autonomy Computer

• Understand the hierarchical architecture of Autonomy Computer.
• Learn how Clusters, Zones, Pods, Containers, and Nodes relate to each other.
• See how Workers and Agents run inside Nodes.
• Explore architectural patterns for different use cases.

​

🤖 How to select and configure models

• See list of available models in the Autonomy Computer from Claude, Llama, DeepSeek, and AWS.
• Select and configure the right model for an agent.

​

⚙️ How to configure apps with environment variables and dependencies

• Set environment variables and provide secrets securely to your Autonomy applications.
• Add Python dependencies using multi-stage Docker builds.

​

🌐 How to create custom APIs for Autonomy apps

• Create custom FastAPI routes tailored to an application’s needs.
• Build both single-agent and parallel multi-agent architectures.
• Implement scalable translation services that process thousands of requests concurrently.
• Deploy custom APIs with proper error handling and documentation.

​

🎨 How to create custom user interfaces for Autonomy apps

• Set up custom user interfaces using modern web frameworks like Nextjs, React, Vue, Angular, or Svelte.
• Configure static file serving in Autonomy Computer, with FastAPI, for production deployments.
• Build streaming chat interfaces that provide real-time AI responses with typewriter effects.
• Create sophisticated user experiences that integrate seamlessly with Autonomy agents.

​

🧠 How to use memory, conversation, and scope in agents

• Configure agents with memory to maintain context across multiple interactions.
• Manage separate conversation threads for different topics or sessions.
• Implement user isolation using scope to prevent memory leakage between users.
• Build custom APIs with sophisticated memory management patterns.

​

🔧 How to give agents tools

• Create Python tools by defining functions that agents can invoke.
• Set up MCP (Model Context Protocol) servers for external service integration.
• Build agents with web search capabilities using Brave Search MCP server.
• Deploy tool-enabled agents with proper configuration and secrets management.

​

⚡ How to use workers and messaging

• Create workers that process messages asynchronously.
• Send messages to workers and receive replies.
• Start workers on the same machine or distribute them across different machines.
• Build distributed applications that scale across multiple pods.
• Discover and communicate with nodes in other pods for parallel processing.

​

🚨 How to diagnose errors

• Diagnose common errors that cause immediate failures.
• Fix message serialization errors (dict vs JSON string).
• Implement proper error handling and timeout patterns.
• Clean up workers to prevent resource leaks.
• Test progressively from simple to complex.
• Understand deployment timing and cold start behavior.

​

📊 How to visualize workers across a zone

• Build a real-time dashboard to visualize all workers running across nodes.
• Create API endpoints to list workers grouped by node.
• Display workers with interactive D3.js visualization.
• Monitor worker creation and deletion in real-time.
• Track worker distribution across multiple pods.

​

Common Autonomy Commands

# Install
curl -sSfL autonomy.computer/install | bash && . "$HOME/.autonomy/env"

# Enroll and get cluster
autonomy cluster enroll --no-input
autonomy cluster show

# Manage zones
autonomy zone list
autonomy zone deploy
autonomy zone delete --yes

# View logs - see "How to View Logs" section below for complete instructions

​

How to View Logs

IMPORTANT: Never run autonomy zone inlet --to logs without backgrounding it - this will block your terminal. Always use the pattern below.

# Start a portal to the logs server in your zone in background, and capture output.
autonomy zone inlet --to logs > logs_portal.log 2>&1 &
LOGS_PID=$!

# Wait for the portal to start and extract its port
sleep 3
LOGS_PORT=$(grep -o "localhost:[0-9]*" logs_portal.log | cut -d: -f2 | head -1)
if [ -z "$LOGS_PORT" ]; then
    LOGS_PORT=32101  # fallback to default port
fi

echo "Portal to the logs server in your zone running on port: $LOGS_PORT (PID: $LOGS_PID)"

# Open logs UI in browser - shows all pods/containers with live updates
open "http://127.0.0.1:$LOGS_PORT"

# Get the full pod name and stream logs to terminal
POD_NAME=main-pod
CONTAINER_NAME=main
FULL_POD_NAME=$(timeout 10s curl -s "127.0.0.1:$LOGS_PORT/" | grep -o 'main-pod-[a-z0-9]*-[a-z0-9]*' | head -1)
timeout 30s curl -N "127.0.0.1:$LOGS_PORT/pods/$FULL_POD_NAME/containers/$CONTAINER_NAME" | head -50

# Always clean up the portal process
kill $LOGS_PID

• The & at the end runs the portal in background (non-blocking)
• Always capture the LOGS_PID so you can stop the portal later
• Use timeout with curl to prevent hanging
• The -N flag with curl disables buffering for streaming
• The | head -50 limits output to 50 lines
• If the portal is not starting, kill all portals using pkill -f "autonomy zone inlet", and try starting it again.

​

Testing with curl

# Test API with streaming - always include timeout
timeout 15s curl --silent --request POST \
--header "Content-Type: application/json" \
--data '{"message":"Your message here"}' \
"https://${CLUSTER}-${ZONE}.cluster.autonomy.computer/agents/${AGENT_NAME}?stream=true"

# Test API without streaming (returns complete response)
timeout 15s curl --silent --request POST \
--header "Content-Type: application/json" \
--data '{"message":"Your message here"}' \
"https://${CLUSTER}-${ZONE}.cluster.autonomy.computer/agents/${AGENT_NAME}"

​

📖 Definitions

​

Autonomy

1. Autonomy Framework: The Autonomy Framework is an open-source python framework to develop apps and products that leverage teams of collaborating AI agents to autonomously accomplish goals.
2. Autonomy Computer: The Autonomy Computer is a cloud-based runtime to run, connect, and scale apps built using the Autonomy Framework. It provides managed infrastructure to run highly scalable and secure autonomous products.
3. Autonomy Command: The Autonomy Command is a command-line program to build apps using the Autonomy Framework and run them on the Autonomy Computer.

​

Agents

• Has a unique identity.
• Uses a large language model to understand, reason, and make autonomous decisions.
• Has memory, so it can retain and recall information over time, to make better autonomous decisions.
• Invokes tools to gather new information and take actions.
• Makes plans that break down complex tasks into small iterative steps.
• Can retrieve knowledge beyond the training data of its language model.
• Collaborates with and can delegate work to other agents.

​

Models

​

Memory

​

Tools

​

Best Practices

• Reference the getting started guide for file templates when creating new apps.
• Start simple - create minimal working examples first, then enhance.
• Zone names must be ≤10 characters.
• Memory is conversation-local, not global.
• Generate README.md with ASCII architecture diagrams for new apps.