Create Your First Agent: From Zero to Intelligence
Let’s create a simple but intelligent agent that demonstrates RunAgent’s core superpower:
1
Initialize the Magic
runagent init my_agentcd my_agent
What RunAgent just created for you:
my_agent/├── main.py # Your agent's brain (two smart functions)├── email_agent.py # Mock AI client (no API keys needed!) ├── runagent.config.json # The bridge to other languages└── __init__.py # Python package magic
Pro insight: This isn’t just boilerplate. Each file serves a specific purpose in making your Python agent accessible from any programming language.
2
Peek Under the Hood: See Your Agent's Brain
Your agent has two functions that will become universally accessible APIs:
The “Aha!” Moment: These Python functions accept message and role parameters. That’s exactly what you’ll pass from JavaScript, Rust, or any other language—RunAgent handles the translation!
3
The Configuration Bridge
Open runagent.config.json to see how Python functions become universal APIs:
runagent run --id agent_abc123 --local --tag minimal \ --message "Explain why the sky is blue" \ --role user
Live output:
🚀 RunAgent Configuration: Agent ID: agent_abc123 Tag: minimal Local: Yes🔍 Auto-resolved address: 127.0.0.1:8000🤖 Executing agent: agent_abc123✅ Agent execution completed!The sky appears blue due to a phenomenon called Rayleigh scattering...
What just happened? You called your Python function from the command line with zero setup!
from runagent import RunAgentClient# Connect to your agent (replace with your actual agent_id)ra = RunAgentClient( agent_id="agent_abc123", entrypoint_tag="minimal", local=True)# Call your agent like it's a local functionresult = ra.run( message="Analyze the benefits of remote work for software teams", role="user")print(result)
The magic: This feels like calling a local Python function, but it’s actually making network calls to your deployed agent!
First, install in your JS project:
npm install runagent
Then use your Python agent from JavaScript:
import { RunAgentClient } from 'runagent';const ra = new RunAgentClient({ agentId: "agent_abc123", entrypointTag: "minimal", local: true});await ra.initialize();const result = await ra.run({ message: 'What makes a great engineering team?', role: 'user'});console.log(result);
Mind-bending reality: JavaScript developers are now calling your Python AI agent as if it were native JavaScript code!
You can connect using the server URL instead of agent_id:
from runagent import RunAgentClientra = RunAgentClient( host="localhost", port=8000, entrypoint_tag="minimal", local=True)result = ra.run(message="Hello from any language!")print(result)
Why this matters: You can deploy to any server and connect from anywhere!
Watch your Python agent stream responses in real-time to any language:
🔥 CLI - Live Streaming
Python SDK - Pythonic Streaming
JavaScript - Async Iterator Magic
Rust - High-Performance Streaming
Go - Streaming
Experience real-time AI streaming in your terminal:
runagent run --id agent_abc123 --local --tag minimal_stream \ --message "Write a creative story about AI agents"
Live streaming output:
🚀 RunAgent Configuration: Agent ID: agent_abc123 Tag: minimal_stream Local: Yes🔍 Auto-resolved address: 127.0.0.1:8000Once upon a time, in a digital realm far beyond the clouds...[STREAM COMPLETE]
What’s happening: Your Python generator function is streaming across the network in real-time!
from runagent import RunAgentClient# Connect to streaming entrypoint (note the '_stream' tag)ra = RunAgentClient( agent_id="agent_abc123", entrypoint_tag="minimal_stream", local=True)# Stream responses as they generatefor chunk in ra.run( message="Explain quantum computing step by step"): print(chunk, end="", flush=True)
The beauty: This looks like a normal Python iterator, but chunks are streaming from your deployed agent in real-time!
import { RunAgentClient } from 'runagent';const ra = new RunAgentClient({ agentId: "agent_abc123", entrypointTag: "minimal_stream", // The magic '_stream' suffix local: true});await ra.initialize();const stream = await ra.run({ message: 'Write a poem about coding'});// Modern JavaScript async iterationfor await (const chunk of stream) { process.stdout.write(chunk);}
Mind-blown moment: JavaScript developers are consuming real-time streams from your Python agent using native async iterators!
use runagent::client::RunAgentClient;use serde_json::json;use futures::StreamExt;#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> { let client = RunAgentClient::new("agent_abc123", "minimal_stream", true).await?; let mut stream = client.run_stream(&[ ("message", json!("Explain machine learning concepts")) ]).await?; while let Some(chunk) = stream.next().await { print!("{}", chunk?); } Ok(())}
Performance revelation: Rust developers get zero-copy streaming from your Python agent with full type safety!
package mainimport ( "context" "fmt" "log" "time" "github.com/runagent-dev/runagent/runagent-go/runagent/pkg/client")func main() { c, err := client.NewWithAddress("841debad-7433-46ae-a0ec-0540d0df7314", "minimal_stream", true, "localhost", 8450) if err != nil { log.Fatal(err) } defer c.Close() ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) defer cancel() s, err := c.RunStream(ctx, map[string]interface{}{"role": "user", "message": "Analyze the benefits of remote work for software teams"}) if err != nil { log.Fatal(err) } defer s.Close() for { data, hasMore, err := s.Next(ctx) if err != nil { log.Fatal(err) } if !hasMore { break } fmt.Printf("Received: %v\n", data) }}
The Revolutionary Insight: Your Python function signature automatically defines the API contract for all programming languages. Change the Python function, and all language SDKs automatically adapt!
Most common fix: Make sure your agent is still running:
runagent serve . # Keep this running in one terminal
Then use the SDK in another terminal or Python script. The agent needs to stay active to receive requests!
My entrypoint tag isn't found
Check your configuration: The tag in your SDK call must exactly match what’s in runagent.config.json:
cat runagent.config.json | grep -A 5 "entrypoints"
Remember: streaming tags must end with _stream!
I get import errors with framework templates
Install the dependencies: Framework templates come with requirements:
pip install -r requirements.txt # For LangGraph, CrewAI, etc.
Port 8000 is already in use
Use a different port:
runagent serve . --port 8080
Then connect using port=8080 in your SDK calls.
🎉 Congratulations! You’ve just experienced the future of AI development. Your Python agents can now be accessed from any programming language with the same ease as calling local functions. This is just the beginning—imagine what you’ll build next!
Ready to go deeper? Join our Discord community to see what other developers are creating with RunAgent!