Getting started

SwarmNode enables you to run Python agents in the cloud without managing servers. An agent can be executed via the UI, REST API and Python SDK.

Create an agent

Agents can be created from the UI on app.swarmnode.ai/agents/create/ or via REST API and Python SDK. In the following sections, we will focus on the UI.

An agent consists of three key components: script, requirements, and environment variables.

• Script is your Python script that will be executed.

• Requirements are the Python packages that your script depends on. For example, if your script uses the requests package, you need to add it to the requirements.

• Environment variables are the variables that your script can access during execution.

Only script is required. Requirements and environment variables are optional.

Script

Write your Python script as you normally would. The only necessity is that the script includes a def main function, which will be executed. The main function can have either zero parameters or one parameter: request.

def main():
    # Your code goes here

def main(request):
    # Your code goes here

Both approaches are valid. Refer to the Request section for more information.

You can use the code editor to add your script:

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

def main(request):
    """Translate text from one language to another."""

    text = request.payload["text"]
    source = request.payload["source"]
    target = request.payload["target"]

    model = ChatOpenAI(model="gpt-4o-mini")
    messages = [
        SystemMessage(f"Translate from {source} to {target}"),
        HumanMessage(text),
    ]
    response = model.invoke(messages)
    return response.content

Requirements

If your script depends on any Python packages, you need to add them to the requirements. Each package should be on a separate line:

langchain==0.3.11
langchain-core==0.3.24
langchain-openai==0.2.12

Environment variables

If your script depends on any environment variables, you need to add them to the environment variables. Each variable should be on a separate line:

OPENAI_API_KEY=sk-...

Execute an agent

After an agent is created, build process will start which will take a few seconds. Once the build is complete, you can execute the agent.

Often, it's useful to execute an agent programmatically. You can do so via REST API and Python SDK.

Here's how you can execute an agent via Python SDK:

import swarmnode

swarmnode.api_key = "YOUR_API_KEY"

agent = swarmnode.Agent.retrieve(id="AGENT_ID")
execution = agent.execute()

You can copy the agent's ID from the UI.

Request

As mentioned above, the main function can have either zero parameters or one parameter: request. request is an object with one attribute: payload.

payload is a any JSON-serializable value that was passed to the execution via REST API or Python SDK:

def main(request):
    print(request.payload)

Payload

payload is a any JSON-serializable value that was passed to the execution via REST API or Python SDK:

Here's how to pass a payload via the SDK:

import swarmnode

swarmnode.api_key = "YOUR_API_KEY"

agent = swarmnode.Agent.retrieve(id="AGENT_ID")
execution = agent.execute(payload={"foo": "bar"})

Here's how to access the payload from the script:

def main(request):
    print(request.payload)  # prints {"foo": "bar"}

Logging

You can use the print function to log messages. You can also use the logging module:

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

handler = logging.StreamHandler()
handler.setLevel(logging.INFO)

logger.addHandler(handler)

def main():
    logger.info("From the logging module")
    print("From the print function")

Logs can be viewed from the UI.

Logs can also be retrieved via REST API and Python SDK. Here's how to access logs via the SDK:

import swarmnode

swarmnode.api_key = "YOUR_API_KEY"

agent = swarmnode.Agent.retrieve(id="AGENT_ID")
execution = agent.execute()
print(execution.logs)

Return value

The return value of the main function must be JSON-serializable:

def main():
    return "Hello world"  # ok

def main():
    return object()  # error

Return values can be viewed from the UI:

Return value can also be retrieved via REST API and Python SDK. Here's how to access return value via the SDK:

import swarmnode

swarmnode.api_key = "YOUR_API_KEY"

agent = swarmnode.Agent.retrieve(id="AGENT_ID")
execution = agent.execute()
print(execution.return_value)