# Delfhos

> Delfhos is a Python SDK for building AI agents that use real tools — Gmail, SQL databases, Google Drive, Sheets, Docs, Calendar, web search, REST APIs, and your own custom functions — with clean orchestration and safe, human-in-the-loop execution.

Python SDK (>= 3.9, Apache-2.0, v0.8.7) for building AI agents that write and execute Python to use real tools — Gmail, SQL, Google Drive/Sheets/Docs/Calendar, web search, REST APIs, and custom functions — with safe, human-in-the-loop, sandboxed execution.

Each section below is available as raw markdown (append nothing — the URL already ends in `.md`). For everything in one request, fetch [/llms-full.txt](https://delfhos.com/llms-full.txt).

## Tutorials

[Tutorials (markdown)](https://delfhos.com/docs/tutorials.md): Learning-oriented, step-by-step lessons. Start here.

- [Tutorial 1 — Your First Agent](https://delfhos.com/docs/tutorials.md#tutorial-1-your-first-agent)
- [Tutorial 2 — Connecting to Gmail](https://delfhos.com/docs/tutorials.md#tutorial-2-connecting-to-gmail)
- [Tutorial 3 — Custom Tools](https://delfhos.com/docs/tutorials.md#tutorial-3-custom-tools)
- [Tutorial 4 — Chat Mode and Memory](https://delfhos.com/docs/tutorials.md#tutorial-4-chat-mode-and-memory)

## How-to Guides

[How-to Guides (markdown)](https://delfhos.com/docs/how-to.md): Task-oriented recipes that solve one specific problem each.

- [How to connect to a SQL database](https://delfhos.com/docs/how-to.md#how-to-connect-to-a-sql-database)
- [How to connect to Google Sheets](https://delfhos.com/docs/how-to.md#how-to-connect-to-google-sheets)
- [How to connect to Google Drive](https://delfhos.com/docs/how-to.md#how-to-connect-to-google-drive)
- [How to connect to Google Docs, Calendar, and more](https://delfhos.com/docs/how-to.md#how-to-connect-to-google-docs-calendar-and-more)
- [How to connect to any REST API](https://delfhos.com/docs/how-to.md#how-to-connect-to-any-rest-api)
- [How to use local or custom OpenAI-compatible models](https://delfhos.com/docs/how-to.md#how-to-use-local-or-custom-openai-compatible-models)
- [How to use multiple LLMs for different tasks](https://delfhos.com/docs/how-to.md#how-to-use-multiple-llms-for-different-tasks)
- [How to control what a tool can do with `allow` and `confirm`](https://delfhos.com/docs/how-to.md#how-to-control-what-a-tool-can-do-with-allow-and-confirm)
- [How to require human approval before actions](https://delfhos.com/docs/how-to.md#how-to-require-human-approval-before-actions)
- [How to run a task: blocking, async, or background](https://delfhos.com/docs/how-to.md#how-to-run-a-task-blocking-async-or-background)
- [How to poll a running request](https://delfhos.com/docs/how-to.md#how-to-poll-a-running-request)
- [How to run many tasks concurrently](https://delfhos.com/docs/how-to.md#how-to-run-many-tasks-concurrently)
- [How to expose the agent over HTTP](https://delfhos.com/docs/how-to.md#how-to-expose-the-agent-over-http)
- [How to use two Gmail accounts in one agent](https://delfhos.com/docs/how-to.md#how-to-use-two-gmail-accounts-in-one-agent)
- [How to enable tool prefiltering to reduce costs](https://delfhos.com/docs/how-to.md#how-to-enable-tool-prefiltering-to-reduce-costs)
- [How to add long-term memory to an agent](https://delfhos.com/docs/how-to.md#how-to-add-long-term-memory-to-an-agent)
- [How to inspect a connection's available actions](https://delfhos.com/docs/how-to.md#how-to-inspect-a-connections-available-actions)
- [How to configure cost tracking](https://delfhos.com/docs/how-to.md#how-to-configure-cost-tracking)
- [How to pass API keys programmatically](https://delfhos.com/docs/how-to.md#how-to-pass-api-keys-programmatically)
- [How to add a system prompt](https://delfhos.com/docs/how-to.md#how-to-add-a-system-prompt)
- [How to configure the execution sandbox](https://delfhos.com/docs/how-to.md#how-to-configure-the-execution-sandbox)
- [How to allow extra Python libraries in the sandbox](https://delfhos.com/docs/how-to.md#how-to-allow-extra-python-libraries-in-the-sandbox)
- [How to pass input files to the agent workspace](https://delfhos.com/docs/how-to.md#how-to-pass-input-files-to-the-agent-workspace)
- [How to extract output files from a task result](https://delfhos.com/docs/how-to.md#how-to-extract-output-files-from-a-task-result)
- [How to retry on failure](https://delfhos.com/docs/how-to.md#how-to-retry-on-failure)
- [How to use `rerun()` for adaptive replanning](https://delfhos.com/docs/how-to.md#how-to-use-rerun-for-adaptive-replanning)

## Reference

[Reference (markdown)](https://delfhos.com/docs/reference.md): Complete API: classes, parameters, return types, errors.

- [`Agent`](https://delfhos.com/docs/reference.md#agent)
- [`Response`](https://delfhos.com/docs/reference.md#response)
- [`StreamSnapshot` and `StreamEvent`](https://delfhos.com/docs/reference.md#streamsnapshot-and-streamevent)
- [`@tool` decorator](https://delfhos.com/docs/reference.md#tool-decorator)
- [`Gmail`](https://delfhos.com/docs/reference.md#gmail)
- [`SQL`](https://delfhos.com/docs/reference.md#sql)
- [`Sheets`](https://delfhos.com/docs/reference.md#sheets)
- [`Drive`](https://delfhos.com/docs/reference.md#drive)
- [`Docs`](https://delfhos.com/docs/reference.md#docs)
- [`Calendar`](https://delfhos.com/docs/reference.md#calendar)
- [`WebSearch`](https://delfhos.com/docs/reference.md#websearch)
- [`APITool`](https://delfhos.com/docs/reference.md#apitool)
- [`Chat`](https://delfhos.com/docs/reference.md#chat)
- [`LLMConfig`](https://delfhos.com/docs/reference.md#llmconfig)
- [`Memory`](https://delfhos.com/docs/reference.md#memory)
- [Error classes](https://delfhos.com/docs/reference.md#error-classes)
- [Supported LLM models](https://delfhos.com/docs/reference.md#supported-llm-models)
- [Environment variables](https://delfhos.com/docs/reference.md#environment-variables)
- [File locations](https://delfhos.com/docs/reference.md#file-locations)
- [Public API surface](https://delfhos.com/docs/reference.md#public-api-surface)

## Explanation

[Explanation (markdown)](https://delfhos.com/docs/explanation.md): How and why Delfhos works under the hood.

- [The two-package architecture](https://delfhos.com/docs/explanation.md#the-two-package-architecture)
- [How the orchestration loop works](https://delfhos.com/docs/explanation.md#how-the-orchestration-loop-works)
- [How memory retrieval works](https://delfhos.com/docs/explanation.md#how-memory-retrieval-works)
- [How the `allow` and `confirm` permission model works](https://delfhos.com/docs/explanation.md#how-the-allow-and-confirm-permission-model-works)
- [How the approval system works](https://delfhos.com/docs/explanation.md#how-the-approval-system-works)
- [How tool code generation works](https://delfhos.com/docs/explanation.md#how-tool-code-generation-works)
- [How the dual-LLM architecture reduces costs](https://delfhos.com/docs/explanation.md#how-the-dual-llm-architecture-reduces-costs)
- [How Chat auto-summarization works](https://delfhos.com/docs/explanation.md#how-chat-auto-summarization-works)
- [How APITool works](https://delfhos.com/docs/explanation.md#how-apitool-works)
- [How the execution sandbox works](https://delfhos.com/docs/explanation.md#how-the-execution-sandbox-works)
- [How `rerun()` works](https://delfhos.com/docs/explanation.md#how-rerun-works)
- [Permission model philosophy](https://delfhos.com/docs/explanation.md#permission-model-philosophy)

## Full

- [Complete documentation, single file](https://delfhos.com/llms-full.txt): Everything above concatenated as flat markdown.
- [GitHub repository](https://github.com/DavidFraifer/Delfhos): Source code and issues.