.prompt and .agent Files

Humanloop provides serialized File formats (.prompt, .agent) for storing Prompts and Agents as human-readable, version-control-friendly files. These formats enable you to integrate your Prompts and Agents into standard software development workflows.

File Types

Humanloop currently supports the following File formats:

• .prompt — Serialized representation of a Prompt
• .agent — Serialized representation of an Agent

Usage

The Humanloop SDK supports working with local Files in your codebase, enabling a code-first development approach.

1
from humanloop import Humanloop
2
3
# Initialize the client with local File support
4
client = Humanloop(
5
  api_key="YOUR_HUMANLOOP_API_KEY",
6
  use_local_files=True # Enable using Files from the local filesystem
7
)
8
9
# Call a local Prompt by referencing its path
10
response = client.prompts.call(
11
  path="welcome-email", # Looks for humanloop/welcome-email.prompt
12
  inputs={"customer_name": "John Doe", "product_name": "Humanloop"}
13
)

For detailed instructions on syncing and using local Files, see our Store Prompts in code guide.

Format Structure

Both .prompt and .agent files follow the same basic structure:

1. YAML frontmatter section (enclosed between ---): Contains all configuration parameters including model selection, generation parameters, and tool definitions. The frontmatter defines how the Prompt or Agent will execute when called.
2. JSX-inspired content section: Contains the template content with a syntax similar to JSX. This includes system messages, user prompts, and variable placeholders using {{variable_name}} syntax.

The formats are nearly identical, with .agent files having just two additional parameters (max_iterations and tools[].on_agent_call) to control execution flow.

Basic Format Example

1
---
2
model: gpt-4o
3
temperature: 0.7
4
max_tokens: -1
5
provider: openai
6
endpoint: chat
7
tools: []
8
// Agent-specific parameters (only in .agent files):
9
// max_iterations: 5
10
// tools[].on_agent_call: "continue" or "stop"
11
---
12
13
<system>
14
  You are a friendly assistant.
15
</system>

Multi-modality and images

Images can be specified using nested <image> tags within a <user> message. To specify text alongside the image, use a <text> tag.

1
<user>
2
  <text>
3
    What is in this image?
4
  </text>
5
  <image url="https://example.com/image.jpg" />
6
</user>

Tools, tool calls, and tool responses

Tools are specified in the YAML header as a JSON array. Both .prompt and .agent files can include tools, though .agent files include additional configuration for tool execution control.

Assistant messages can contain either text or tool requests. For tool requests, use a <tool> tag within an <assistant> tag with attributes name and id. The text wrapped in the <tool> tag should be a JSON-formatted string containing the tool call’s arguments.

Tool responses can then be added with standalone <tool> tags after the <assistant> message, using the same name and id to link the response to the request.

1
---
2
model: gpt-4o
3
temperature: 0.7
4
max_tokens: -1
5
provider: openai
6
endpoint: chat
7
tools: [
8
  {
9
    "name": "get_current_weather",
10
    "description": "Get the current weather in a given location",
11
    "parameters": {
12
      "type": "object",
13
      "properties": {
14
        "location": {
15
          "type": "string",
16
          "name": "Location",
17
          "description": "The city and state, e.g. San Francisco, CA"
18
        },
19
        "unit": {
20
          "type": "string",
21
          "name": "Unit",
22
          "enum": [
23
            "celsius",
24
            "fahrenheit"
25
          ]
26
        }
27
      },
28
      "required": [
29
        "location"
30
      ]
31
    }
32
  }
33
]
34
---
35
<system>
36
  You are a friendly assistant.
37
</system>
38
39
<user>
40
  What is the weather in SF?
41
</user>
42
43
<assistant>
44
  <tool name="get_current_weather" id="call_1ZUCTfyeDnpqiZbIwpF6fLGt">
45
    {
46
      "location": "San Francisco, CA"
47
    }
48
  </tool>
49
</assistant>
50
51
<tool name="get_current_weather" id="call_1ZUCTfyeDnpqiZbIwpF6fLGt">
52
  Cloudy with a chance of meatballs.
53
</tool>

Related Resources

• Store Files in code - Detailed guide on how to store serialized Files in your codebase
• Prompts - Learn more about how Prompts work in Humanloop
• Agents - Learn more about how Agents work in Humanloop