YoMo Documentation

To build an AI agent with LLM Function Calling, follow these steps:

1. Initialize the project: Run yomo init to scaffold a new project structure.
2. Implement logic: Edit the application code (e.g., ./app/src/app.ts in TypeScript projects).
3. Run the tool: Use the yomo run command to execute your tool with a specific name.

yomo init
yomo run -n <tool-name> <path-to-app>

Example for a weather tool:

yomo run -n get-weather ./app

Launch the YoMo server to begin managing LLM tools and agents. You can use a custom configuration file by passing the --config flag.

If you are using Ollama as your LLM provider, ensure you have pulled the desired model first (e.g., ornith).

yomo serve
# Or with a custom config
yomo serve --config path/to/config.yaml

Install the YoMo CLI using the official installation script. After installation, verify it by checking the version.

curl -fsSL https://get.yomo.run | sh
yomo --version

When a Tool connects to the Zipper, it must initiate a handshake. The HandshakeRequest identifies the tool and provides authentication, while the HandshakeResponse confirms whether the connection is accepted.

HandshakeRequest fields

• name: A unique tool name used for routing.
• credential: A token used for authentication.
• json_schema: An optional JSON schema string describing the tool's input/output contract.

HandshakeResponse fields

• status_code: An HTTP-like status code indicating the result.
• error_msg: A message describing why the handshake was rejected.

Messages are the building blocks of a chat request. Each Message consists of a Role and Content.

Roles

• System: Sets the behavior of the assistant.
• Developer: Used for developer-level instructions.
• User: The human user's input.
• Assistant: The model's previous responses.
• Tool: The output from a tool execution (requires a tool_call_id).

Content Types

Content can be a simple Text string or a collection of Parts for multimodal inputs:

• Text: Plain text content.
• Image: An image provided via image_url.
• InputAudio: Audio data for multimodal models.
• File: File content provided via file_id or direct data/URL.

Note: When using Role::Tool, you MUST provide a non-empty tool_call_id to associate the message with the original tool call.

YoMo's Go serverless implementation uses a specific framing protocol for reading and writing data over a connection. Every packet is encoded as follows:

1. Length Prefix: A 4-byte big-endian uint32 indicating the size of the following JSON data.
2. JSON Payload: The actual serialized JSON object.

To implement this manually or understand the underlying transport, use the big-endian byte order for the length prefix.

Tools can be invoked by sending an HTTP POST request to the endpoint /{tool_name}.

Request Details

• Method: POST
• Path: /{tool_name} (where tool_name is the identifier of the tool you wish to call).
• Headers: You can pass tracing metadata using the following headers:
  • X-Trace-Id
  • X-Span-Id
  • X-Extension
• Body: The raw bytes of the request are forwarded to the tool.

Response Formats

The API response behavior depends on the BodyFormat returned by the tool in its ResponseHeaders:

• Bytes: The tool returns a standard HTTP response with the body content.
• Chunk: The API responds with an SSE (Server-Sent Events) stream, allowing the client to consume data chunks as they are produced.
• Null: Returns an empty response with StatusCode::OK.

To use the YoMo Node.js serverless entrypoint, you must implement a ToolModule in a file located at ./src/app.ts. The entrypoint expects an exported object that follows the ToolModule structure.

Your module must export a handler function which is the core logic of your tool. This handler receives args (the parsed JSON arguments) and an optional agentContext (a record of strings provided by the agent). You can also optionally export a description string to describe what your tool does.

Once the server is running and your tool is active, you can interact with the AI agent using the /v1/chat/completions endpoint. This endpoint follows a standard chat completion format.

curl http://127.0.0.1:9001/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{ "messages": [ { "role": "user", "content": "Your prompt here" } ] }'

curl http://127.0.0.1:9001/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "role": "user",
      "content": "I am going for a hike on the Yarra Bend Park Loop. What should I wear?"
    }
  ]
}'

You can bypass the LLM agent and call a specific serverless tool directly via the /tool/<tool-name> endpoint. The request body must include an args field containing a JSON string of the arguments.

curl --request POST \
--url http://127.0.0.1:9001/tool/<tool-name> \
--header 'Content-Type: application/json' \
--data '{"args":"{\"key\":\"value\"}"}'

curl \
  --request POST \
  --url http://127.0.0.1:9001/tool/get-weather \
  --header 'Content-Type: application/json' \
  --data '{"args":"{\"city\":\"London\"}"}'