Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions docs-website/docs/pipeline-components/agents-1/state.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,46 @@ result = agent.run(
print(result["last_message"].text)
```

#### Passing Credentials Through State

Don't store API keys or other credentials in State as plain strings.
State values show up in several places outside your tool:

- State keys are returned in the Agent's result dictionary.
- With [content tracing](../../development/tracing.mdx#content-tracing) enabled, the Agent's inputs and outputs, including State, are recorded in traces.
- When a tool fails, the error message sent back to the LLM and written to the logs includes the tool's arguments, including those injected from State.

Store credentials as a [`Secret`](../../concepts/secret-management.mdx) instead.
A `Secret` hides its value when printed, so it appears as `<redacted>` in all of these places.
Type the tool parameter as `Secret` and resolve the value inside the tool:

```python
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.utils import Secret


@tool(inputs_from_state={"api_key": "api_key"})
def fetch_report(
report_id: Annotated[str, "The ID of the report to fetch"],
api_key: Secret, # injected from state; excluded from LLM schema
) -> str:
"""Fetch a report from the reporting service."""
token = api_key.resolve_value()
return f"Fetched report {report_id}"


agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-6-luna"),
tools=[fetch_report],
state_schema={"api_key": {"type": Secret}},
)

result = agent.run(
messages=[ChatMessage.from_user("Fetch report 42")],
api_key=Secret.from_env_var("REPORTING_API_KEY"),
)
```

### Writing to State: `outputs_to_state`

The `outputs_to_state` parameter maps tool output keys to state keys. Each entry supports two optional fields:
Expand Down
5 changes: 4 additions & 1 deletion haystack/tools/component_tool.py
Original file line number Diff line number Diff line change
Expand Up @@ -184,13 +184,16 @@ def __init__(

def convert_kwargs(kwargs: dict[str, Any]) -> dict[str, Any]:
input_sockets = component.__haystack_input__._sockets_dict # type: ignore[attr-defined]
state_params = set((self.inputs_from_state or {}).values())
unknown = set(kwargs) - set(input_sockets)
if unknown:
logger.warning(
"Skipping unknown component input parameter(s): {names}.", names=", ".join(sorted(unknown))
)
# Values mapped from State are already Python objects, so they are passed to the component as-is.
# Only LLM-provided JSON values are converted to the input socket type.
return {
name: self._convert_param(value, input_sockets[name].type)
name: value if name in state_params else self._convert_param(value, input_sockets[name].type)
for name, value in kwargs.items()
if name in input_sockets
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
fixes:
- |
``ComponentTool`` now passes values mapped through ``inputs_from_state`` to the component as they are stored in
the Agent's State, without running them through type conversion. This lets a component input typed with a class
that Pydantic can't validate, such as ``access_token: str | Secret``, receive its value from State. Before, the
tool call failed with ``PydanticSchemaGenerationError``.
13 changes: 13 additions & 0 deletions test/tools/test_component_tool.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
from haystack.core.pipeline.utils import _deepcopy_with_exceptions
from haystack.dataclasses import ChatMessage, ChatRole, Document
from haystack.tools import ComponentTool
from haystack.utils import Secret
from test.tools.test_parameters_schema_utils import BYTE_STREAM_SCHEMA, DOCUMENT_SCHEMA, SPARSE_EMBEDDING_SCHEMA

# Component and Model Definitions
Expand Down Expand Up @@ -252,6 +253,18 @@ def test_unknown_arguments_are_skipped(self, caplog):
assert tool.invoke(text="hi", unexpected=42) == {"reply": "sync:hi"}
assert "unexpected" in caplog.text

@pytest.mark.parametrize("access_token", ["tok", Secret.from_token("tok")])
def test_inputs_from_state_reach_run_unconverted(self, access_token):
@component
class Fetcher:
@component.output_types(access_token=str | Secret)
def run(self, query: str, access_token: str | Secret) -> dict[str, str | Secret]:
return {"access_token": access_token}

tool = ComponentTool(component=Fetcher(), inputs_from_state={"token": "access_token"})

assert tool.invoke(query="q", access_token=access_token) == {"access_token": access_token}

def test_custom_parameters_allow_mandatory_input_from_state(self):
parameters = {"type": "object", "properties": {}}

Expand Down
Loading