Skip to main content
An agent that you train on Oumi can run outside Oumi. pi is one of the most popular open-source agent harnesses for the terminal. It sends your prompt to a model, runs the tools that the model calls, and sends the tool results back until the model answers. You deploy your fine-tuned model on Oumi, implement its tools as a pi extension, and add a custom model to pi that points to your Oumi deployment. You do not write or maintain an agent loop of your own. pi supplies the loop, the terminal interface, and the session history, and your small fine-tuned model supplies the tool-calling behavior at a fraction of the cost and latency of a frontier model. In this guide, your model is the main model of the pi session and sees only the tools and system prompt from its training data. To keep your usual model in pi and call your agent only when you need it, run it as a subagent instead. This guide uses a stock lookup agent as its example. The agent has two tools: search_company finds the ticker symbol for a company name, and get_stock_price returns the latest price for a ticker.

HOW THE PIECES CONNECT

The pi agent loop on your machine sends messages and tools to your Oumi deployment, runs each tool call in your pi extension, and returns the final reply to you The pi agent loop on your machine sends messages and tools to your Oumi deployment, runs each tool call in your pi extension, and returns the final reply to you Oumi serves the model. pi runs everything else on your machine, including your tool code, so your tools can reach real data that Oumi cannot.

BEFORE YOU START

You will need:
  • An Oumi project.
  • pi, installed on your machine by following the pi quickstart instructions.
  • A personal Oumi API key from User Settings > API Keys.

1

Train a tool-calling model

Ask FAiE to help you build the agent, or follow the agents workflow yourself:
  1. Create a tool for each function that your agent calls. For the example, create search_company and get_stock_price.
  2. Give each tool a tool implementation. A simulated implementation is enough to generate training data. pi calls your real code later.
  3. Collect the prompts that your agent must handle, and generate training conversations with a strong teacher model.
  4. Train a base model that supports tool calling on the best conversations.
  5. Evaluate the trained model against the teacher with your tools attached.
Keep a copy of the system prompt from your training data. You use it again in pi.
2

Deploy the model

Deploy your trained model and wait until the deployment is Active. Copy its model path from the deployment page. The model path has the form projects/{project_id}/deployments/{deployment_id}.Save your Oumi API key in a file, for example ~/.config/oumi/api.key, and make it readable only by you:
3

Implement the tools in pi

During training or evaluation on the Oumi platform, a tool implementation answered each tool call. In pi, an extension answers it. An extension is a TypeScript file in ~/.pi/agent/extensions/ that registers the tools your model knows how to call.The model learned your tools from their Oumi definitions. Make each pi tool match its Oumi tool:
  • Name: The same toolName, for example search_company. If the names differ, the model calls a tool that pi does not have.
  • Parameters: The same parameter names, types, and required fields.
  • Description: The same text, or text that is very close to it.
Create ~/.pi/agent/extensions/stock-tools.ts:
stock-tools.ts
A tool that finds no match returns a result that says so. A tool whose data source fails throws an error, and pi shows that error to the model as a failed tool call. Neither path invents a value.
You can have pi write the extension for you. Start pi with a frontier model, paste the JSON of each Oumi tool from its detail page, and ask: “Write a pi extension in ~/.pi/agent/extensions/ that implements these tools with the same names and parameters. Use <your data source> to answer them.” Review the code before you load it, because an extension runs with your user’s permissions.
pi loads the extensions in ~/.pi/agent/extensions/ when it starts. If pi is already running, run /reload.
4

Add the deployment to pi

Add an oumi provider to ~/.pi/agent/models.json. Create the file if it does not exist. If it exists, add the oumi entry inside providers.
~/.pi/agent/models.json
5

Select the model and run the agent

Start pi with your model, only your tools, and the system prompt from your training data, so that the model gets the same context as in your evaluations:
By default, pi also gives the model its own coding tools (read, bash, edit, and write) and a system prompt for coding work. If your model did not see these during training, you may want to consider starting pi with --tools and --system-prompt, as in the command above. Otherwise, the model can call a coding tool instead of your tools, or answer without calling a tool.
Then ask a question such as “How is Nucor doing today?”. The model calls search_company to find the ticker NUE, calls get_stock_price with that ticker, and answers with the price that the tool returned. pi shows each tool call and its result in the transcript.

TROUBLESHOOTING

  • 429 with “Deployment is warming up”: Your deployment uses scale-to-zero and has no warm replica. Wait a few minutes and send the prompt again. To prevent cold starts, set min replicas to 1.
  • 400 with “Invalid model format”: The id in models.json is not a model path. Set id to projects/{project_id}/deployments/{deployment_id} and put the label in name.
  • The model does not appear in /model: pi cannot get an API key for the provider. Run the apiKey command yourself, for example cat ~/.config/oumi/api.key, and make sure it prints your key.
  • The model calls a tool that pi does not have: A tool name in your extension does not match the toolName in Oumi. Rename the pi tool, then run /reload.
  • The model answers without calling tools, or calls the coding tools: Start pi with --tools and --system-prompt as shown in the last step, so that the model sees the same tools and instructions as in training.

WHAT’S NEXT

Run your agent as a subagent

Keep your usual model in pi and give it your agent as a tool.

Calling your endpoint

Call your deployment from your own code with the OpenAI or Anthropic SDKs.

Inference logs

Review the requests that pi sent to your deployment.

Compounding intelligence

Find where your deployed model struggles, and retrain it on targeted data.

Tools

Write tool definitions that a model calls correctly.