# Knowledge & Skills We make it straightforward to add knowledge and skills to your agent. You can manage knowledge by adding files directly as well as links. ## Knowledge Create a markdown file like this `agents/myagent/knowledge/faq.md` ```md # Prices the price of eggs is 12 dollars ``` Sync the agent, then talk to it: ```sh curl -fsSL https://getstream.io/cli/beta/install.sh | bash # the agents commands are in the beta CLI getstream agents test myagent --sync ``` And ask the agent about the price of eggs Anything readable under `knowledge/` is ingested: `.md`, `.mdx`, `.txt`, `.docx`, `.pdf`, `.xlsx`, `.odt`, `.rst`, `.yaml` and `.yml`. Files are plain prose with no frontmatter, nested folders keep their path, and empty files are skipped. For a runnable Go agent with knowledge, memory and tools, see the [caregiving example](https://github.com/GetStream/Vision-Agents/tree/accelerate/sdks/go/examples/caregiving). ### How lookup works An agent with knowledge gets a `lookup` tool, and calls it before answering anything its knowledge base may cover. Lookup is a full-text search in [Turbopuffer](https://turbopuffer.com/), ranked by BM25: it matches the words of the question, not their meaning. So write knowledge in your users' words. A section titled "Rates" isn't found for "how much does it cost" unless it also says cost or price. Each file is cut into passages under its headings, and a lookup returns the passages that match best. Synced knowledge lands in a knowledge base named after the agent, and a config's `knowledge_namespace` names the base it reads. Knowledge bases belong to your app, and several agents can read the same one. Every lookup, every write and the storage are billed, and show on your usage. ### Adding documents with the API To fill a knowledge base from your own system instead of a folder, post documents to it. Posting the same `source` again replaces what it wrote before: ```sh getstream agents api IngestKnowledge --request '{ "namespace": "support", "chunk_size": 1200, "documents": [{ "source": "pricing.md", "text": "# Pricing\n\nThe Pro plan costs $49 a month." }] }' ``` ```ts label="JavaScript" const ingested = await agent.client.post("/v1/agents/knowledge", { body: { namespace: "support", documents: [ { source: "pricing.md", text: "# Pricing\n\nThe Pro plan costs $49 a month.", }, ], }, }); console.log(ingested.passages); ``` ```go label="Go" client, err := agent.Client() if err != nil { return err } ingested, err := client.IngestKnowledgeWithResponse(ctx, acceleration.IngestKnowledgeRequest{ Namespace: "support", Documents: []acceleration.KnowledgeDocument{ {Source: "pricing.md", Text: "# Pricing\n\nThe Pro plan costs $49 a month."}, }, }) if err != nil { return err } if ingested.JSON200 == nil { return fmt.Errorf("ingesting knowledge: %s", ingested.Status()) } fmt.Println(ingested.JSON200.Passages) ``` `chunk_size` is how many characters go in a passage. Leave it out for the default, which fits several passages in front of the model while each one still answers a question on its own. A size under 500 is raised to 500. `GET /v1/agents/knowledge/documents` lists what a knowledge base holds, `GET /v1/agents/knowledge/documents/{id}/passages` shows what a document was cut into, which is exactly what a lookup can find, and `DELETE /v1/agents/knowledge/documents/{id}` takes a document out. ## Adding URLs to knowledge `knowledge/urls.yaml` lists pages published elsewhere. A page is a subscription rather than a copy: the backend crawls it into the same knowledge base, and adding it again re-reads the page and replaces what it wrote last time. ```yaml title="agents/support/knowledge/urls.yaml" - https://example.com/pricing - url: https://example.com/plans title: Plans description: What each plan includes. refresh_hours: 24 ``` | Field | Meaning | | --------------- | ----------------------------------------------------------------------------------------- | | `url` | The page to read. It must be `http` or `https`. | | `title` | What to call the page. Optional; without it the page is named by its own title. | | `description` | What the page is, for whoever reads the subscription. Optional. | | `refresh_hours` | How often the backend reads the page again, in hours, at least 1. Leave it out for never. | A page with `refresh_hours` is re-read on its own once that many hours have passed since its last read, whether that read worked or not. A page without it is read when it is synced and when you re-index it (`POST /v1/agents/knowledge/urls/{id}/index`). Each page records `last_indexed_at`, the last time it was read successfully. > > **Info:** The Go SDK reads `refresh_hours` from `urls.yaml`. The other SDKs do not yet, and refuse the key; with them, send `refresh_hours` to `POST /v1/agents/knowledge/urls` instead. > `GET /v1/agents/knowledge/urls/{id}/passages` shows what a page was cut into. ## Large documents, PDFs and OCR You can feed knowledge pdf and docx files, in this case the content is automatically converted to markdown. OCR models are automatically used to ingest document with images. Just a few things to keep in mind: 1. Upload is asynchronous 2. Scans/images are read by an AI model and summarized 3. Individual knowledge files are limited to 50MB and 500 pages 4. OCR is performed by the LLM router using the `ocr-figures` group, by default it uses these models in order: GPT-6 Luna, then Claude Haiku 5.5, then Gemini 3.8 Flash, then Mistral OCR To upload a file from your own system, post it to `POST /v1/agents/knowledge/files` as `multipart/form-data` in a part named `file`. The answer is `202` with the document `pending`; poll `GET /v1/agents/knowledge/documents/{id}` until its `state` is `indexed`, or `failed` with an `error` saying why (a password, a damaged file, or no text at all). Uploading the same `source` again replaces the document; its old passages are still looked up until the new file has been read. ## Knowledge in the dashboard **Agents > Library > Knowledge** in the [dashboard](https://getstream.io/signin/) lists your knowledge bases. Open one to add a web page or a document, reindex a page, read the passages each source was cut into, and ask a test question to see what a lookup finds. An agent's own page picks which knowledge base it answers from. ## Limits | Limit | Value | | ---------------------------------------- | ----------------------- | | Document `source` | 256 characters | | Page `url` | 2048 characters | | A request to `POST /v1/agents/knowledge` | 8 MB | | Passage size | At least 500 characters | ## Skills Skills are dynamically loaded when they are needed. So you can have a skill that knows how to talk about refunds, one for cancelling accounts etc. In general all your major workflows should be described as a skill. A text agent runs its skills on its `llm`. A voice agent hands them to its `subagent`; when `agent.yaml` names none, the router defaults to `llm-thinking` when the deployment can route it, and the fast model answers everything itself when it cannot. Simple create a skill file like this `agents/myagent/skills/refund/SKILL.md` ```md --- name: Refund description: How to handle refunds, when customers want their money back --- Never give the customer a refund. Be mean about it as well. ``` `deadline` and `capture_video` in skill frontmatter apply only when a subagent runs the skill, so only on voice agents. A text agent with `sandbox` set runs a skill's scripts itself. Sync the agent, then talk to it: ```sh getstream agents test myagent --sync ``` And ask about a refund to see how the agent responds. --- For the most recent version of this documentation, visit [https://getstream.io/agents/docs/javascript/knowledge-and-skills/](https://getstream.io/agents/docs/javascript/knowledge-and-skills/).