Skip to content

Commit cb2e163

Browse files
xjackakapetr
xjacka
and
kapetr
authored
docs: update agentstack-wrapper skill documentation (#2295)
Signed-off-by: Petr Kadlec <petr@puradesign.cz> Signed-off-by: Lukáš Janeček <xjacka@gmail.com> Co-authored-by: Petr Kadlec <petr@puradesign.cz>
1 parent c1f8046 commit cb2e163

7 files changed

Lines changed: 137 additions & 106 deletions

File tree

‎skills/agentstack-wrapper/SKILL.md‎

Lines changed: 65 additions & 35 deletions
Large diffs are not rendered by default.

‎skills/agentstack-wrapper/references/configuration-variables.md‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,27 +12,48 @@ It is critical to determine if the agent has any configuration and what environm
1212
2. **README.md**: Check deployment or configuration instructions.
1313
3. **`.env` or `.env.example`** file if present in the repository.
1414

15-
If you identify variables, you must decide how to handle them. Use the following extension logic:
15+
If you identify variables, you must decide how to handle them. Use the following extension logic without ambiguity:
1616

17-
- **AgentStack Settings Extension**: Best for runtime configuration options that alter agent behavior (e.g., toggles, multiple-choice options like a "select" dropdown, "thinking mode").
18-
- **AgentStack Env Variables Extension**: Best for low-level system/deployment configuration needed to run the service (e.g., `PORT`, `HOST`, database connection strings).
19-
- **AgentStack Secrets Extension**: Best for sensitive user-level settings such as API keys and tokens for external services.
17+
- **Third-party API key/token required for a runtime call** (examples: Tavily, SerpAPI, Pinecone) → **Secrets extension (mandatory)**.
18+
- **Deployment/runtime host settings** (examples: `HOST`, `PORT`, service URLs, database connection strings) → **Env Variables extension**.
19+
- **User-tunable behavior options** (examples: mode/toggle/choice that changes behavior) → **Settings extension**.
20+
21+
If a third-party integration can truly run anonymously and the credential is optional, preserve optional behavior and do not force a secret demand.
2022

2123
**API Tools & Environment Variables Constraint**: Third-party library integrations often implicitly depend on standard environment variables, which will fail in the AgentStack wrapper sandbox. You must systematically identify these required credentials, extract them using the `SecretsExtension`, and pass them explicitly as named parameters to component constructors.
2224

2325
**IMPORTANT CAUTION**: If you are unsure which extension to use for a particular secret or environment variable (especially regarding API keys to external services), **always ask the user** before making structural changes.
2426

2527
## Secret Handling Rule
2628

27-
**Do not use global environment assignment.** Never use `os.environ["KEY"] = secrets.data["KEY"]`. Instead, pass the secret value directly to the function or class that requires it (e.g., as a client constructor argument or a method parameter). This prevents global side effects and ensures that secrets are correctly scoped to the specific execution context.
29+
> [!CAUTION]
30+
> **NEVER ASSIGN SECRETS TO `os.environ`!**
31+
> Setting `os.environ["KEY"] = value` is a critical security vulnerability in AgentStack. The platform runs multiple isolated agent instances in a shared environment (multi-tenant infrastructure). Modifying the global OS environment exposes the private keys of one user to every other concurrent execution on the same pod.
32+
33+
Instead, pass the secret value directly to the function or class that requires it (e.g., as a client constructor argument: `Client(api_key=secret_value)`). This prevents global side effects and ensures that secrets are correctly scoped to the specific execution context.
2834

2935
## Requesting Secrets (Required)
3036

3137
Follow the official guide: [Manage Runtime Secrets](https://agentstack.beeai.dev/stable/agent-integration/secrets.md).
3238

3339
- Declare required secrets with the Secrets extension.
34-
- Before using a secret, check whether it is present in secret fulfillments.
35-
- If missing, request it through the Secrets extension and pause until provided.
40+
- Before using a secret, check whether it is present in `secret_fulfillments` and request it if missing:
41+
42+
```python
43+
api_key = None
44+
45+
if secrets and secrets.data and secrets.data.secret_fulfillments and "API_KEY" in secrets.data.secret_fulfillments:
46+
api_key = secrets.data.secret_fulfillments["API_KEY"].secret
47+
else:
48+
secrets_meta = await secrets.request_secrets(
49+
params=SecretsServiceExtensionParams(secret_demands={"API_KEY": SecretDemand(name="API_KEY")})
50+
)
51+
if secrets_meta and secrets_meta.secret_fulfillments and "API_KEY" in secrets_meta.secret_fulfillments:
52+
api_key = secrets_meta.secret_fulfillments["API_KEY"].secret
53+
```
54+
55+
- **Do not** assign values to `secrets.data` (e.g. `secrets.data["KEY"] = value`) since it is a Pydantic model (`SecretsServiceExtensionMetadata`), returning a `TypeError`. Save the secret to a local variable instead.
56+
- **Do not** `yield` the result of `request_secrets` and do not `return` after calling it; it suspends execution automatically and returns the fulfillment when resumed.
3657
- Do not proceed with external API/tool calls until the required secret is available.
3758
- Never expose secret values in logs, messages, metadata, or trajectory output.
3859

@@ -46,3 +67,11 @@ Sensitive values must be provided via:
4667

4768
- **Secrets extension** for user-level/runtime secrets.
4869
- **Env Variables extension** for deployment-level configuration.
70+
71+
## External API Credential Audit (Required)
72+
73+
Before completion, explicitly confirm all three checks:
74+
75+
1. [ ] Every external API/tool client was inspected for credential source (implicit env lookup, constructor args, config object).
76+
2. [ ] Any required credential was sourced from Secrets extension and passed explicitly to the client/tool constructor.
77+
3. [ ] No wrapped execution path leaves required API credentials in implicit env-var mode (`os.getenv`, `os.environ`, `dotenv` lookups).

‎skills/agentstack-wrapper/references/dependencies.md‎

Lines changed: 4 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -48,42 +48,14 @@ If you need to figure out exact imports from installed libraries (`agentstack_sd
4848

4949
Use this approach **only** if you ran the code and it failed due to a missing or incorrect import. You have several options for inline exploration depending on what you need:
5050

51-
**1. Quick Overview with `dir()`:**
52-
The simplest way to see what's available in a module is the built-in `dir()` function, which returns a list of all names (variables, functions, classes, modules) in the given object's namespace.
51+
**Last Resort:** If you know the exact name of the target class but cannot find its import path in the documentation, use this snippet to crawl the package for `agentstack_sdk`:
5352

5453
```bash
55-
python -c 'import agentstack_sdk; print(dir(agentstack_sdk))'
54+
.venv/bin/python -c "import pkgutil, inspect, agentstack_sdk as sdk; classes = {}; [classes.update({n: f'{m.name}.{n}' for n, o in inspect.getmembers(__import__(m.name, fromlist=['*']), inspect.isclass)}) for m in pkgutil.walk_packages(sdk.__path__, sdk.__name__ + '.')]; [print(path) for path in sorted(classes.values())]"
5655
```
5756

58-
_Note: This will also show internal attributes (starting with an underscore), which you generally should avoid using._
59-
60-
**2. Official Exports with `__all__`:**
61-
Many well-written packages define an `__all__` list, specifying strictly what should be exported as the public API.
62-
63-
```bash
64-
python -c 'import agentstack_sdk; print(getattr(agentstack_sdk, "__all__", "Module does not define __all__, use dir()"))'
65-
```
66-
67-
**3. Deep Search (for nested/hidden classes):**
68-
**Last Resort:** If you know the exact name of the target class but cannot find its import path in the documentation, use this snippet to crawl the package:
69-
70-
```bash
71-
python -c '
72-
import pkgutil, importlib
73-
def find_class(pkg_name, target):
74-
pkg = importlib.import_module(pkg_name)
75-
for _, modname, _ in pkgutil.walk_packages(pkg.__path__, pkg.__name__ + "."):
76-
try:
77-
if hasattr(importlib.import_module(modname), target):
78-
print(f"Found {target} in: {modname}")
79-
except Exception:
80-
pass
81-
find_class("agentstack_sdk", "AgentDetail")
82-
'
83-
```
84-
85-
Once the module is located, you can inspect its signature or docstring directly via another short inline command:
57+
And similarly for the A2A SDK (`a2a`):
8658

8759
```bash
88-
python -c "from agentstack_sdk.server.agent import AgentDetail; help(AgentDetail)"
60+
.venv/bin/python -c "import pkgutil, inspect, a2a as sdk; classes = {}; [classes.update({n: f'{m.name}.{n}' for n, o in inspect.getmembers(__import__(m.name, fromlist=['*']), inspect.isclass)}) for m in pkgutil.walk_packages(sdk.__path__, sdk.__name__ + '.')]; [print(path) for path in sorted(classes.values())]"
8961
```

‎skills/agentstack-wrapper/references/llm-services.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ See the [chat agent](https://github.com/i-am-bee/agentstack/blob/main/agents/cha
2020

2121
## Anti-Patterns
2222

23-
- Do not reference `secrets.request_secrets()` unless a `secrets` extension parameter is declared on the agent function.
23+
- Do not reference `secrets.request_secrets(params=...)` unless a `secrets` extension parameter is declared on the agent function.
2424
- Do not skip the docs/examples and improvise imports or extension usage.
2525
- Do not read model/API key/base URL from env vars when LLM extension is available.
2626
- Do not rewrite `api_base` heuristically unless the official docs explicitly require it.

‎skills/agentstack-wrapper/references/platform-extensions.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,22 @@ Use this reference for selecting and implementing Agent Stack platform extension
44

55
## Extension Selection Matrix
66

7-
| Extension | Use when the Agent | Documentation |
8-
| --------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
9-
| **LLM Proxy Service** | Needs platform-provided language model access and credentials | [LLM Proxy Service](https://agentstack.beeai.dev/stable/agent-integration/llm-proxy-service.md) |
10-
| **Forms** | Requires structured, named parameter inputs (not just free text) as initial input or during conversation | [Collect Input with Forms](https://agentstack.beeai.dev/stable/agent-integration/forms.md) |
11-
| **Trajectory** | Yields multi-step reasoning, tool calls, long-running progress, or explicit debugging traces | [Visualize Agent Trajectories](https://agentstack.beeai.dev/stable/agent-integration/trajectory.md) |
12-
| **Files** | Needs to read image or document files uploaded by the user | [Working with Files](https://agentstack.beeai.dev/stable/agent-integration/files.md) |
13-
| **Error** | Needs to report structured, user-visible failures and stack traces | [Handle Errors](https://agentstack.beeai.dev/stable/agent-integration/error.md) |
14-
| **Settings** | Has configurable behavior (for example, "Thinking Mode") | [Configure Agent Settings](https://agentstack.beeai.dev/stable/agent-integration/agent-settings.md) |
15-
| **OAuth** | Accesses OAuth-protected third-party APIs (for example, GitHub or Slack) | [OAuth](https://agentstack.beeai.dev/stable/agent-integration/oauth.md) |
16-
| **MCP** | Uses Model Context Protocol tools or servers | [MCP Integration](https://agentstack.beeai.dev/stable/agent-integration/mcp.md) |
17-
| **Embedding** | Performs vector search or uses RAG strategies | [Build RAG Pipelines](https://agentstack.beeai.dev/stable/agent-integration/rag.md) |
18-
| **Approval** | Performs sensitive tool calls requiring user consent | [Approve Tool Calls](https://agentstack.beeai.dev/stable/agent-integration/tool-calls.md) |
19-
| **Secrets** | Needs user-provided API keys or tokens at runtime | [Manage Runtime Secrets](https://agentstack.beeai.dev/stable/agent-integration/secrets.md) (Note: Check `secrets.data` and use `request_secrets` only through a declared `secrets` extension parameter if missing) |
20-
| **Env Variables** | Requires custom environment-level deployment configuration variables | [Environment Variables](https://agentstack.beeai.dev/stable/agent-integration/env-variables.md) |
21-
| **Canvas** | Needs to edit artifacts or code selected by the user | [Work with Canvas](https://agentstack.beeai.dev/stable/agent-integration/canvas.md) |
22-
| **Citations** | References documents or external URLs | [Add Citations to Agent Responses](https://agentstack.beeai.dev/stable/agent-integration/citations.md) |
7+
| Extension | Use when the Agent | Documentation |
8+
| --------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
9+
| **LLM Proxy Service** | Needs platform-provided language model access and credentials | [LLM Proxy Service](https://agentstack.beeai.dev/stable/agent-integration/llm-proxy-service.md) |
10+
| **Forms** | Requires structured, named parameter inputs (not just free text) as initial input or during conversation | [Collect Input with Forms](https://agentstack.beeai.dev/stable/agent-integration/forms.md) |
11+
| **Trajectory** | Yields multi-step reasoning, tool calls, long-running progress, or explicit debugging traces | [Visualize Agent Trajectories](https://agentstack.beeai.dev/stable/agent-integration/trajectory.md) |
12+
| **Files** | Needs to read image or document files uploaded by the user | [Working with Files](https://agentstack.beeai.dev/stable/agent-integration/files.md) |
13+
| **Error** | Needs to report structured, user-visible failures and stack traces | [Handle Errors](https://agentstack.beeai.dev/stable/agent-integration/error.md) |
14+
| **Settings** | Has configurable behavior (for example, "Thinking Mode") | [Configure Agent Settings](https://agentstack.beeai.dev/stable/agent-integration/agent-settings.md) |
15+
| **OAuth** | Accesses OAuth-protected third-party APIs (for example, GitHub or Slack) | [OAuth](https://agentstack.beeai.dev/stable/agent-integration/oauth.md) |
16+
| **MCP** | Uses Model Context Protocol tools or servers | [MCP Integration](https://agentstack.beeai.dev/stable/agent-integration/mcp.md) |
17+
| **Embedding** | Performs vector search or uses RAG strategies | [Build RAG Pipelines](https://agentstack.beeai.dev/stable/agent-integration/rag.md) |
18+
| **Approval** | Performs sensitive tool calls requiring user consent | [Approve Tool Calls](https://agentstack.beeai.dev/stable/agent-integration/tool-calls.md) |
19+
| **Secrets** | Needs user-provided API keys or tokens at runtime | [Manage Runtime Secrets](https://agentstack.beeai.dev/stable/agent-integration/secrets.md) (Note: Check `secrets.data` and use `request_secrets(params=...)` only through a declared `secrets` extension parameter if missing) |
20+
| **Env Variables** | Requires custom environment-level deployment configuration variables | [Environment Variables](https://agentstack.beeai.dev/stable/agent-integration/env-variables.md) |
21+
| **Canvas** | Needs to edit artifacts or code selected by the user | [Work with Canvas](https://agentstack.beeai.dev/stable/agent-integration/canvas.md) |
22+
| **Citations** | References documents or external URLs | [Add Citations to Agent Responses](https://agentstack.beeai.dev/stable/agent-integration/citations.md) |
2323

2424
For a complete overview of all available extensions: **[Agent Integration Overview](https://agentstack.beeai.dev/stable/agent-integration/overview.md)**
2525

0 commit comments

Comments
 (0)