> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://humanloop.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://humanloop.com/docs/_mcp/server.
> Humanloop File formats allow you to store File configurations alongside your source code. They are human-readable, version-control-friendly, and can be used directly in your applications via the SDK's path parameter.
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](/docs/explanation/prompts)
* `.agent` — Serialized representation of an [Agent](/docs/explanation/agents)
## Usage
The Humanloop SDK supports working with local Files in your codebase, enabling a code-first development approach.
**`Python`**
```python title="Python"
from humanloop import Humanloop
# Initialize the client with local File support
client = Humanloop(
api_key="YOUR_HUMANLOOP_API_KEY",
use_local_files=True # Enable using Files from the local filesystem
)
# Call a local Prompt by referencing its path
response = client.prompts.call(
path="welcome-email", # Looks for humanloop/welcome-email.prompt
inputs={"customer_name": "John Doe", "product_name": "Humanloop"}
)
```
**`TypeScript`**
```typescript title="TypeScript"
import { Humanloop } from "humanloop";
// Initialize the client with local File support
const client = new Humanloop({
apiKey: "YOUR_HUMANLOOP_API_KEY",
useLocalFiles: true # Enable using Files from the local filesystem
});
// Call a local Prompt by referencing its path
const response = await client.prompts.call({
path: "welcome-email", // Looks for humanloop/welcome-email.prompt
inputs: { customer_name: "John Doe", product_name: "Humanloop" }
});
```
For detailed instructions on syncing and using local Files, see our [Store Prompts in code](/docs/development/guides/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
```jsx
---
model: gpt-4o
temperature: 0.7
max_tokens: -1
provider: openai
endpoint: chat
tools: []
// Agent-specific parameters (only in .agent files):
// max_iterations: 5
// tools[].on_agent_call: "continue" or "stop"
---
You are a friendly assistant.
```
> **Note**
>
> Currently, we only support pulling these Files from Humanloop to your local environment.
> However, you can modify local Files and use them directly - when the SDK detects changes to a File,
> it automatically creates a new version for that path. Two-way synchronization is coming soon.
### Multi-modality and images
Images can be specified using nested `` tags within a `` message. To specify text alongside the image, use a `` tag.
**`Image and Text`**
```jsx Image and Text
What is in this image?
```
> **Note**
>
> Currently, the `url` attribute only supports remote URLs (`https://`). Local file paths are not supported yet, though we're exploring this capability for future releases.
### 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 `` tag within an ``
tag with attributes `name` and `id`. The text wrapped in the `` tag should be a JSON-formatted string containing the tool call's arguments.
Tool responses can then be added with standalone `` tags after the `` message,
using the same `name` and `id` to link the response to the request.
```jsx
---
model: gpt-4o
temperature: 0.7
max_tokens: -1
provider: openai
endpoint: chat
tools: [
{
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"name": "Location",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"name": "Unit",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location"
]
}
}
]
---
You are a friendly assistant.
What is the weather in SF?
{
"location": "San Francisco, CA"
}
Cloudy with a chance of meatballs.
```
## Related Resources
* [Store Files in code](/docs/development/guides/store-prompts-in-code) - Detailed guide on how to store serialized Files in your codebase
* [Prompts](/docs/explanation/prompts) - Learn more about how Prompts work in Humanloop
* [Agents](/docs/explanation/agents) - Learn more about how Agents work in Humanloop