Agents

Ockam Agents are intelligent autonomous actors that accomplish complex open ended tasks. Python apps, running in Ockam AI, can create millions of parallel collaborating agents in seconds.

Each agent:

• Has a unique identity.
• Uses a large language model to understand natual language.
• Has memory of conversations.
• Makes plans that break down complex tasks into small iterative steps.
• Can retrieve knowledge beyond the training data of its language model.
• Invokes tools to gather new information and take actions.
• Collaborates with and can delegate work to other agents.

from ockam import Agent, Node


async def main(node):
    await Agent.start(
        node=node,
        name="henry",
        instructions="""
            You are Henry, an expert legal agent
        """
    )


Node.start(main)

​

Build

Let’s build a new app, that provides a Legal AI Agent. Within the app directory, create the following three files:

» tree

├── ockam.yaml
└── images
    └── main
        ├── Dockerfile
        └── main.py

• The ockam.yaml configuration file defines how to deploy a Zone in your Cluster in Ockam AI.
• The images directory contains the source code of docker images that will be used to run containers in your Zone.
  • Inside images, there is a directory for the main image.
    • Dockerfile describe how the main image will be compiled.
    • main.py is the Python program that is run by the main image.

name: 01
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main

The ockam.yaml configuration file defines how to deploy your Zone:

• Create a Zone named 01 .
• Create a Pod named main-podinside the 01 Zone.
• Make the HTTP server, in the main container in this pod, public.
• Run a main container using the main image.

FROM ghcr.io/build-trust/ockam-python:latest
COPY . .
ENTRYPOINT ["python", "main.py"]

The Dockerfile bases the main image on the ockam-python image which already contains the ockam python package. The Dockerfile then copies the contents of the images/main directory into the image and sets main.py as the program to run when the container is started.

from ockam import Agent, Node


async def main(node):
    agent = await Agent.start(
        node=node,
        name="henry",
        instructions="""
            You are Henry, an expert legal assistant.
        """
    )

    reply = await agent.send("who are you?")
    print(reply)


Node.start(main)

The main.py file:

1. Turns your Python app into an Ockam Node. An Ockam Node in your Cluster can connect with and deliver messages to any other Ockam Node in your Cluster that is running in Ockam AI.
2. After the Node is initialized, it invokes the main function defined in your main.py file. The main function starts an agent name henry with specific instructions. It then sends a message to this agent and prints the agent’s reply.
3. Node.start also starts an HTTP server within this Python app.

​

Run

Run the ockam command in the directory that has the ockam.yaml, it will:

1. Build each image in images/ and push them to a container registry that is available to your Zone.
2. Deploy the Zone into your Cluster, in Ockam AI, based on the configuration that you specified above in ockam.yaml.
3. Open two portal inlets on your workstation that connect to corresponding outlets in the main-pod that is running in your Zone in Ockam AI.

. Deploying zone 01 in cluster 25df35de87aa441b88f22a6c2a830a17...

✔ Created a repository for the image main
✔ Built image main
✔ Pushed image main

✔ Deployed zone 01 in cluster 25df35de87aa441b88f22a6c2a830a17

  The http server on the main-pod is available at:
  https://25df35de87aa441b88f22a6c2a830a17-01.ai.ockam.network

✔ Opened a portal to the outlet http on main-pod from tcp://localhost:8000
✔ Opened a portal to the outlet logs on logs-pod from tcp://localhost:3000

​

Logs

You can see the logs for all containers in your deployed zone at http://localhost:3000.

​

HTTP

By default the pod will expose a HTTP interface with a few endpoints interact with the deployed agents.

The public URL for the HTTP server on your pod (each pod will have its own unique URL) is displayed in the example output above:

The http server on the main-pod is available at: https://25df35de87aa441b88f22a6c2a830a17-01.ai.ockam.network

To return a list of all agents send a GET request to the /agents endpoint:

http GET \
"https://25df35de87aa441b88f22a6c2a830a17-01.ai.ockam.network/agents"

To interact with a specific agent, send a POST request to the /agents/<name> endpoint:

http POST \
"https://25df35de87aa441b88f22a6c2a830a17-example001.ai.ockam.network/agents/henry" \
message="who are you?"

For some use cases, especially user-facing ones with potentially long responses, it may be preferable to stream the response. Passing a stream=true parameter to the /agents/<name> endpoint will stream chunked responses from the agent in real-time:

http POST \
"https://25df35de87aa441b88f22a6c2a830a17-01.ai.ockam.network/agents/henry?stream=true" \
message="what is a patent"