Portia SDK Python

Portia AI is an open source developer framework for stateful, authenticated agentic workflows. The core product accessible in this repository is extensible with our complimentary cloud features which are aimed at making production deployments easier and faster. Play around, break things and tell us how you're getting on in our Discord channel (↗). Most importantly please be kind to your fellow humans (Code of Conduct (↗)).

If you want to dive straight in with an example, check out our Google Tools example (↗).

Why Portia AI

Problem	Portia's answer
Planning: Many use cases require visibility into the LLM’s reasoning, particularly for complex tasks requiring multiple steps and tools. LLMs also struggle picking the right tools as their tool set grows: a recurring limitation for production deployments	Multi-agent plans: Our open source, multi-shot prompter guides your LLM to produce a Plan in response to a prompt, weaving the relevant tools, inputs and outputs for every step.
Execution: Tracking an LLM’s progress mid-task is difficult, making it harder to intervene when guidance is needed. This is especially critical for enforcing company policies or correcting hallucinations (hello, missing arguments in tool calls!)	Stateful PlanRuns: Portia will spin up a multi-agent PlanRun to execute on generated plans and track their state throughout execution. Using our Clarification abstraction you can define points where you want to take control of run execution e.g. to resolve missing information or multiple choice decisions. Portia serialises the run state, and you can manage its storage / retrieval yourself or use our cloud offering for simplicity.
Authentication: Existing solutions often disrupt the user experience with cumbersome authentication flows or require pre-emptive, full access to every tool—an approach that doesn’t scale for multi-agent assistants.	Extensible, authenticated tool calling: Bring your own tools on our extensible Tool abstraction, or use our growing plug and play authenticated tool library, which will include a number of popular SaaS providers over time (Google, Zendesk, Hubspot, Github etc.). All Portia tools feature just-in-time authentication with token refresh, offering security without compromising on user experience.

Quickstart

Installation

0. Ensure you have python 3.11 or higher installed. If you need to update your python version please visit their docs.

python --version

1. Install the Portia Python SDK

pip install portia-sdk-python 

2. Ensure you have an API key set up

export OPENAI_API_KEY='your-api-key-here'

3. Validate your installation by submitting a simple maths prompt from the command line

portia-cli run "add 1 + 2"

Note

We support Anthropic and Mistral AI as well and we're working on adding more models asap. For now if you want to use either model you'd have to set up the relevant API key and add one of these args to your CLI command:
portia-cli run --llm-provider="anthropic" "add 1 + 2" or portia-cli run --llm-provider="mistralai" "add 1 + 2"

All set? Now let's explore some basic usage of the product 🚀

E2E example repo

We have a repo that showcases some of our core concepts to get you started. It's available here (↗). We recommend starting with the Google Tools example (↗) if you are brand new to Portia.

E2E example with open source tools

This example is meant to get you familiar with a few of our core abstractions:

• A Plan is the set of steps an LLM thinks it should take in order to respond to a user prompt. They are immutable, structured and human-readable.
• A PlanRun is a unique instantiation of a Plan. The purpose of a PlanRun is to capture the state of a unique plan run at every step in an auditable way.
• Portia orchestrates plan generation and execution, including the creation, pausing and resumption of plan runs.

Before running the code below, make sure you have the following keys set as environment variables in your .env file:

• An OpenAI API key (or other LLM API key) set as OPENAI_API_KEY=
• A Tavily (↗) API key set as TAVILY_API_KEY=

from dotenv import load_dotenv
from portia import Portia, default_config, example_tool_registry

load_dotenv()

# Instantiate a Portia client. Load it with the default config and with the example tools.
portia = Portia(config=default_config(), tools=example_tool_registry)

# Generate the plan from the user query
plan = portia.plan('Which stock price grew faster in 2024, Amazon or Google?')
print(plan.model_dump_json(indent=2))

# Create and execute the run from the generated plan
plan_run = portia.run_plan(plan)

# Serialise into JSON and print the output
print(plan_run.model_dump_json(indent=2))

E2E example with Portia cloud storage

Our cloud offering will allow you to easily store and retrieve plans in the Portia cloud, access our library of cloud hosted tools, and use the Portia dashboard to view plan runs, clarifications and tool call logs. Head over to app.portialabs.ai (↗) and get your Portia API key. You will need to set it as the env variable PORTIA_API_KEY.
Note that this example also requires the environment variables OPENAI_API_KEY (or ANTHROPIC or MISTRALAI if you're using either) and TAVILY_API_KEY as the previous one.

The example below introduces some of the config options available with Portia AI:

• The storage_class is set using the StorageClass.CLOUD ENUM. So long as your PORTIA_API_KEY is set, runs and tool calls will be logged and appear automatically in your Portia dashboard at app.portialabs.ai (↗).
• The default_log_level is set using the LogLevel.DEBUG ENUM to DEBUG so you can get some insight into the sausage factory in your terminal, including plan generation, run states, tool calls and outputs at every step 😅
• The llm_provider, llm_model and xxx_api_key (varies depending on model provider chosen) are used to choose the specific LLM provider and model. In the example below we're splurging and using GPT 4.0!

Finally we also introduce the concept of a tool_registry, which is a flexible grouping of tools.

import os
from dotenv import load_dotenv
from portia import (
    Portia,
    Config,
    StorageClass,
    LogLevel,
    LLMProvider,
    LLMModel,
    example_tool_registry,
)

load_dotenv()
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')

# Load the default config and override the storage class to point to the Portia cloud
my_config = Config.from_default(
    storage_class=StorageClass.CLOUD,
    default_log_level=LogLevel.DEBUG,
    llm_provider=LLMProvider.OPENAI, # You can use `MISTRAL`, `ANTHROPIC` instead
    llm_model_name=LLMModel.GPT_4_O, # You can use any of the available models instead
    openai_api_key=OPENAI_API_KEY # Use `mistralai_api_key=MISTRALAI` or `anthropic_api_key=ANTHROPIC_API_KEY` instead
)

# Instantiate a Portia client. Load it with the config and with the open source example tool registry
portia = Portia(config=my_config, tools=example_tool_registry)

# Execute query.
plan_run = portia.run('Which stock price grew faster in 2024, Amazon or Google?')

# Serialise into JSON an print the output
print(plan_run.model_dump_json(indent=2))

Learn more

• Head over to our docs at docs.portialabs.ai (↗).
• Join the conversation on our Discord channel (↗).
• Watch us embarrass ourselves on our YouTube channel (↗).
• Follow us on Product Hunt (↗).

Contribution guidelines

Head on over to our contribution guide (↗) for details.

Support

We love feedback and suggestions. Please join our Discord channel (↗) to chat with us.

We also particularly appreciate github stars. If you've liked what you've seen, please give us a star at the top of the page.