Portia – open source framework that makes it easy to build Agentic AI workflows!

Portia AI is an open source developer framework for predictable, stateful, authenticated agentic workflows. We allow developers to have as much or as little oversight as they’d like over their multi-agent deployments and we are obsessively focused on production readiness. 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, dive into one of our examples in our Examples Repo (↗).

Iterate on agents’ reasoning and intervene in their execution
🧠 Create your multi-agent Plan conversationally, or build them with our PlanBuilder.
📝 Enrich a PlanRunState during execution to track progress.
🚧 Define inputs and output structures for enhanced predictability.
✋🏼 Add deterministic tasks through an ExecutionHook. Use a clarification for human:agent interactions.

Extensive tool support including MCP support
🔧 Connect tool registries from any MCP server, local tools, Portia cloud tools or another AI tool provider (e.g. ACI.dev).
🌐 Navigate the web and cope with captchas and logins using our open source browser tool.

Authentication for API and web agents
🔑 Handle user credentials seamlessly, for both API tools and browser sessions, with our clarification interface.

Production ready
👤 Attribute multi-agent runs and auth at an EndUser level.
💾 Large inputs and outputs are automatically stored / retrieved in Agent memory at runtime.
🔗 Connect any LLM including local ones, and use your own Redis server for caching.

🌟 Star Portia AI to stay updated on new releases!

To clickthrough at your own pace, please follow this link

Ensure you have python 3.11 or higher installed using python --version. If you need to update your python version please visit their docs. Note that the example below uses OpenAI but we support other models as well. For instructions on linking other models, refer to our docs.

Step 1: Install the Portia Python SDK

pip install portia-sdk-python

Step 2: Ensure you have an LLM API key set up

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

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

portia-cli run "add 1 + 2"

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

You will need a Portia API key for this one because we use one of our cloud tools to schedule a calendar event and send an email. We have a free tier so you do not need to share payment details to get started. Head over to app.portialabs.ai (↗) and get your Portia API key. You will then need to set it as the env variable PORTIA_API_KEY.

The example below introduces some of the config options available with Portia AI (check out our docs (↗) for more):

• 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 and xxx_api_key (varies depending on model provider chosen) are used to choose the specific LLM provider. In the example below we’re using GPT 4o, but you can use Anthropic, Gemini and others!

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

from dotenv import load_dotenv
from portia import Config, Portia, DefaultToolRegistry
from portia.cli import CLIExecutionHooks

load_dotenv(override=True)

recipient_email = input("Please enter the email address of the person you want to schedule a meeting with:\n")
task = f"""
Please help me accomplish the following tasks:
- Get my availability from Google Calendar tomorrow between 8:00 and 8:30
- If I am available, schedule a 30 minute meeting with {recipient_email} at a time that works for me with the title "Portia AI Demo" and a description of the meeting as "Test demo".
"""

config = Config.from_default()
portia = Portia(
   config=config,
   tools=DefaultToolRegistry(config=config),
   execution_hooks=CLIExecutionHooks(),
)

plan = portia.run(task)

Here is an example where we build a customer refund agent using Stripe’s MCP server. It leverages execution hooks and clarifications to confirm human approval before moving money.

Here is another example where we use our open browser tool. It uses clarifications when it encounters a login page to allow a human to enter their credentials directly into the session and allow it to progress.

• 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 (↗).

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

Portia offers a PAID contribution program by fixing issues on our ‘Issues’ list. You can read all about this in the contribution guide (↗).