Store Prompts in code

Humanloop allows you to store Prompt and Agent definitions in your local filesystem and in version control, while still leveraging Humanloop’s prompt management and evaluation capabilities. This guide will walk you through using local Files in your development workflow.

Prerequisites

• A Humanloop account with at least one Prompt or Agent created
• Humanloop SDK installed (which includes the CLI functionality)

1
---
2
model: gpt-4o
3
temperature: 0.7
4
max_tokens: 500
5
top_p: 1.0
6
presence_penalty: 0.0
7
frequency_penalty: 0.0
8
provider: openai
9
endpoint: chat
10
tools: []
11
---
12
13
<system>
14
  You are an email assistant that creates friendly welcome emails for new customers. 
15
  Keep your tone warm and conversational while clearly explaining the key features of our product.
16
</system>
17
18
<user>
19
  Write a welcome email for {{customer_name}} who just signed up for our {{product_name}} service.
20
</user>

$
pip install humanloop

$
# Create a .env file in your project root
$
echo "HUMANLOOP_API_KEY=<YOUR_HUMANLOOP_API_KEY>" > .env

Step 1: Pull Files from Humanloop

After creating your Prompt in Humanloop (like the example Prompt we set up earlier), you’ll see it in your workspace:

Now you can pull this Prompt from Humanloop to your local environment by running:

$
humanloop pull

This command clones your Humanloop workspace into a humanloop directory in your project root, maintaining the same folder structure as your remote workspace.

$
humanloop pull --help

Step 2: Use local Files in your code

Now that you have your Prompt locally, you can use it in your code by configuring the SDK to use local Files.

1
from humanloop import Humanloop
2
3
# Initialize the client with local File support
4
humanloop = Humanloop(
5
  api_key="YOUR_HUMANLOOP_API_KEY",
6
  # Enable using Files from the local filesystem
7
  use_local_files=True, 
8
)
9
10
# Call a local Prompt
11
response = humanloop.prompts.call(
12
  path="welcome-email", # Looks for humanloop/welcome-email.prompt
13
  inputs={"customer_name": "Alex", "product_name": "Humanloop AI Platform"}
14
)
15
16
print(response.logs[0].output)

You can also log results from your own provider calls by referencing local Files:

1
# After making your own provider call, log the results with a local Prompt File
2
humanloop.prompts.log(
3
  path="welcome-email",  # References the local File
4
  messages=[
5
    {"role": "system", "content": "You are an email assistant..."},
6
    {"role": "user", "content": "Write a welcome email..."}
7
  ],
8
  output="The generated email content...",
9
  inputs={"customer_name": "Alex", "product_name": "Humanloop AI Platform"}
10
)

Step 3: Verify local File usage

To verify that your code is actually using the local Prompt, you can make a small modification and observe the change in output.

1. Open humanloop/welcome-email.prompt in a text editor and modify the system message.

1
<system>
2
-You are an email assistant that creates friendly welcome emails for new customers. Keep your tone warm and conversational while clearly explaining the key features of our product.
3
+You are an EXTREMELY ENTHUSIASTIC email assistant that creates friendly welcome emails for new customers. Use LOTS of emojis and exclamation points!! Keep your tone warm and conversational while clearly explaining the key features of our product.
4
</system>

2. Call the modified Prompt from your code:

1
response = humanloop.prompts.call(
2
  path="welcome-email",
3
  inputs={"customer_name": "Alex", "product_name": "Humanloop AI Platform"}
4
)
5
6
print(response.logs[0].output)
7
# The response should now include enthusiastic language and emojis!

You’ll notice in the UI that a log was created with the new version of the Prompt.

Step 4: Version control

Now that your Prompt is a local File, you can add it to your version control system.

$
# Add the humanloop directory to your git repository
$
git add humanloop/
$
git commit -m "Add Humanloop Prompt"

For example, if you update the model in your welcome-email Prompt from gpt-4o to gpt-4o-mini in the Humanloop UI and deploy it, after pulling the changes you would see:

By integrating your Prompts and Agents with version control, you create a more robust development workflow:

• Single source of truth for both code and AI components
• Change history with full audit trail of who changed what and when
• Local experimentation through editing Files directly in your IDE without needing the Humanloop UI
• Deployment safety via pull requests and code reviews for Prompt changes

1
# Call a local Agent
2
agent_response = humanloop.agents.call(
3
  path="customer-service/customer-support", # Looks for humanloop/customer-service/customer-support.agent
4
  messages=[
5
    {
6
      "role": "user",
7
      "content": "I need help with my order: 1234567890"
8
    }
9
  ]
10
)
11
12
# Access agent output
13
print(agent_response.previous_agent_message)

Troubleshooting

If you encounter any issues while working with local Files, check these common solutions:

• API key not detected? Ensure it’s stored in a .env file at the top level and that you run commands from your project root.
• Changes not reflecting? Ensure you’ve deployed your Prompt in the Humanloop UI after making changes.
• SDK not finding files? Ensure the directory used when pulling matches the one in your SDK initialization. (if you used --local-files-directory custom-dir when pulling, specify the same path in your SDK config for local_files_directory/localFilesDirectory).

Next Steps

By integrating Humanloop Files into your development workflow, you’ve bridged the gap between AI development and software engineering practices, making it easier to build robust AI applications.

Now that you’re using local Files, you might want to:

1. Set up continuous integration to automatically test your Prompts and Agents when they change
2. Learn more about the File formats to understand how to manually edit them if needed
3. Explore environment labels to manage different versions for development, staging, and production